[output] Roll out structured output across commands and workflows (#33) (#146)

* [output] Add initial structured changelog check output (#33)

* Update wiki submodule pointer for PR #146

* [tests] Finalize structured output format metadata (#33)

* [output] Encapsulate structured responses in a command responder (#33)

* Update wiki submodule pointer for PR #146

* [refactor] Clarify command responder naming (#33)

* [refactor] Remove legacy resolved responder names (#33)

* Update wiki submodule pointer for PR #146

* [output] Expand structured changelog command responses (#33)

* Update wiki submodule pointer for PR #146

* [output] Add structured changelog entry responses (#33)

* Update wiki submodule pointer for PR #146

* [output] Add structured changelog show responses (#33)

* Update wiki submodule pointer for PR #146

* [output] Add structured agents responses (#33)

* Update wiki submodule pointer for PR #146

* [output] Add structured skills responses (#33)

* Update wiki submodule pointer for PR #146

* [output] Rename structured output flag and add code-style support (#33)

* Update wiki submodule pointer for PR #146

* [output] Add structured refactor responses (#33)

* Update wiki submodule pointer for PR #146

* [output] Add structured phpdoc responses (#33)

* Update wiki submodule pointer for PR #146

* [output] Add structured docs responses (#33)

* Update wiki submodule pointer for PR #146

* [output] Add structured metrics responses (#33)

* Update wiki submodule pointer for PR #146

* [output] Add structured reports responses (#33)

* Update wiki submodule pointer for PR #146

* [output] Add structured standards responses (#33)

* Update wiki submodule pointer for PR #146

* [output] Add structured tests responses (#33)

* Update wiki submodule pointer for PR #146

* [output] Add structured sync responses (#33)

* Update wiki submodule pointer for PR #146

* Add log output formatter and formatted logger to console.

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

* [output] Migrate command output handling to logger (#33)

* Update wiki submodule pointer for PR #146

* [output] Migrate remaining managed-file commands to logger (#33)

* Update wiki submodule pointer for PR #146

* [output] Simplify logger context processing (#33)

* Update wiki submodule pointer for PR #146

* [output] Replace output format option with json flag (#33)

* Update wiki submodule pointer for PR #146

* [output] Refine json logging defaults and command context (#33)

* Update wiki submodule pointer for PR #146

* [output] Quiet nested tool output in json mode (#33)

* [docs] Align structured json command documentation (#33)

* Update wiki submodule pointer for PR #146

* [ci] Emit GitHub Actions command annotations (#33)

* Update wiki submodule pointer for PR #146

* [output] Normalize command result helper usage (#33)

* Update wiki submodule pointer for PR #146

* [output] Normalize remaining command result helpers (#33)

* Update wiki submodule pointer for PR #146

* [workflow] Group queued command output in GitHub Actions (#33)

* Update wiki submodule pointer for PR #146

* [logger] Move GitHub Actions error annotations into logger (#33)

* Update wiki submodule pointer for PR #146

* [cli] Invert progress flags and simplify workflow labels (#33)

* [tests] Stabilize GitHub Actions output expectations (#33)

* [docs] Align output, progress, and workflow guidance (#33)

* [review] Preserve resolved docs source in failure logs (#33)

* [logger] Make LoggerAwareCommandInterface explicit (#33)

* Update wiki submodule pointer for PR #146

* [phpdoc] Restore descriptive command and workflow docs (#33)

* Update wiki submodule pointer for PR #146

---------

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.github/wiki

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add structured command output across the DevTools command surface with `--json` and `--pretty-json`, including pretty-printed JSON and agent-aware JSON defaults (#33)
+- Group queued subprocess output and emit GitHub Actions workflow annotations for clearer CI logs and error surfaces (#33)
+
+### Changed
+
+- Propagate structured output flags through nested DevTools subprocesses, simplify logger context extraction, and keep machine-readable runs quieter by default (#33)
+- Adopt `--progress` as the positive opt-in for transient progress rendering while keeping supported commands quiet by default (#33)
+
+### Fixed
+
+- Stabilize logger and process-queue test expectations in CI by making GitHub Actions output detection deterministic during the PHPUnit suite (#33)
+
 ## [1.16.0] - 2026-04-20
 
 ### Changed

CHANGELOG.md

@@ -76,19 +76,26 @@ composer --working-dir=packages/example metrics
 # Add one changelog entry to Unreleased or a published version
 composer changelog:entry "Add changelog automation for release workflows (#28)"
 composer changelog:entry --type=fixed --release=1.2.0 --date=2026-04-19 "Preserve published release sections during backfill (#28)"
+composer changelog:entry --json "Add changelog automation for release workflows (#28)"
+composer changelog:entry --pretty-json "Add changelog automation for release workflows (#28)"
 
 # Verify that the current branch added a meaningful Unreleased entry
 composer changelog:check
 composer changelog:check --against=origin/main
+composer changelog:check --json
+composer changelog:check --pretty-json
 
 # Infer the next semantic version from Unreleased
 composer changelog:next-version
+composer changelog:next-version --json
 
 # Promote Unreleased into a published version
 composer changelog:promote 1.3.0
+composer changelog:promote 1.3.0 --json
 
 # Render one published section as release notes
 composer changelog:show 1.3.0
+composer changelog:show 1.3.0 --json
 
 # Check and fix code style using ECS and Composer Normalize
 composer code-style
@@ -168,6 +175,27 @@ next semantic version from pending changes, `changelog:promote` publishes the
 current `Unreleased` section into a tagged version, and `changelog:show`
 renders one published section for GitHub release notes.
 
+Structured output is available across the DevTools command surface through
+`--json`, which returns deterministic `message` / `level` / `context` payloads
+for CI, bots, and AI-agent workflows while preserving the normal
+human-readable terminal output by default. Use `--pretty-json` when you want
+the same structured payload indented for manual inspection in a terminal.
+`--pretty-json` also implies JSON output, so there is no need to pass both
+flags together. In agent environments, DevTools can also switch to JSON
+automatically when the runtime is detected as agent-driven. For
+`changelog:show`, the default text mode still prints the raw release-notes
+body so release workflows can keep piping it directly into GitHub releases.
+
+Progress output is disabled by default on the commands that support transient
+rendering, and `--progress` re-enables it for human-readable terminal runs.
+When `--json` or `--pretty-json` is active on commands that orchestrate other
+tools, DevTools keeps progress suppressed, forwards JSON flags where the
+underlying tool supports structured output, and otherwise falls back to
+quieter subprocess modes so the captured payload stays machine-readable. In
+GitHub Actions, queued subprocess output is grouped into collapsible sections,
+and logged failures emit native workflow error annotations, including file and
+line metadata when commands provide it.
+
 When the packaged changelog workflow is synchronized into a consumer
 repository, pull requests are expected to add a notable changelog entry before
 merge. The same workflow can be triggered manually to prepare a release bump

README.md

@@ -44,6 +44,7 @@
         "composer/composer": "^2.9",
         "container-interop/service-provider": "^0.4.1",
         "dg/bypass-finals": "^1.9",
+        "ergebnis/agent-detector": "^1.1",
         "ergebnis/composer-normalize": "^2.51",
         "ergebnis/rector-rules": "^1.18",
         "fakerphp/faker": "^1.24",

composer.json

@@ -20,7 +20,12 @@ Usage
 Options
 -------
 
-This command does not accept additional options.
+This command supports:
+
+- ``--json`` to emit a structured machine-readable payload instead of the
+  normal terminal output;
+- ``--pretty-json`` to emit the same structured payload with indentation for
+  terminal inspection.
 
 Examples
 --------

docs/commands/agents.rst

@@ -31,16 +31,21 @@ Usage
 
    composer changelog:entry "Add changelog automation for release workflows (#28)"
    composer changelog:entry --type=fixed --release=1.2.0 --date=2026-04-19 "Preserve published release sections during backfill (#28)"
+   composer changelog:entry --json "Add changelog automation for release workflows (#28)"
 
    composer changelog:check
    composer changelog:check --against=origin/main
+   composer changelog:check --json
 
    composer changelog:next-version
+   composer changelog:next-version --json
 
    composer changelog:promote 1.3.0
    composer changelog:promote 1.3.0 --date=2026-04-19
+   composer changelog:promote 1.3.0 --json
 
    composer changelog:show 1.3.0
+   composer changelog:show 1.3.0 --json
 
 Options
 -------
@@ -55,34 +60,54 @@ Options
    - ``--date=<YYYY-MM-DD>`` when a published section should carry a release
      date immediately;
    - ``--file=<path>`` to work with a changelog file other than
-     ``CHANGELOG.md``.
+     ``CHANGELOG.md``;
+   - ``--json`` to emit a structured machine-readable payload instead of the
+     normal terminal output;
+   - ``--pretty-json`` to emit the same structured payload with indentation for
+     terminal inspection.
 
 ``changelog:check``
    Supports:
 
    - ``--against=<git-ref>`` to compare the current changelog against a base
      branch or commit;
-   - ``--file=<path>`` to validate another changelog path.
+   - ``--file=<path>`` to validate another changelog path;
+   - ``--json`` to emit a structured machine-readable payload instead of the
+     normal terminal output;
+   - ``--pretty-json`` to emit the same structured payload with indentation for
+     terminal inspection.
 
 ``changelog:next-version``
    Supports:
 
    - ``--current-version=<semver>`` when the current published version should
      be supplied explicitly instead of inferred from the changelog;
-   - ``--file=<path>`` to inspect another changelog path.
+   - ``--file=<path>`` to inspect another changelog path;
+   - ``--json`` to emit a structured machine-readable payload instead of the
+     normal terminal output;
+   - ``--pretty-json`` to emit the same structured payload with indentation for
+     terminal inspection.
 
 ``changelog:promote``
    Supports:
 
    - the required version argument;
    - ``--date=<YYYY-MM-DD>`` to control the published release date;
-   - ``--file=<path>`` to promote another changelog path.
+   - ``--file=<path>`` to promote another changelog path;
+   - ``--json`` to emit a structured machine-readable payload instead of the
+     normal terminal output;
+   - ``--pretty-json`` to emit the same structured payload with indentation for
+     terminal inspection.
 
 ``changelog:show``
    Supports:
 
    - the required version argument;
-   - ``--file=<path>`` to render another changelog path.
+   - ``--file=<path>`` to render another changelog path;
+   - ``--json`` to emit a structured machine-readable payload instead of the
+     raw release-note text;
+   - ``--pretty-json`` to emit the same structured payload with indentation for
+     terminal inspection.
 
 Behavior
 --------
@@ -91,13 +116,27 @@ Behavior
   when the selected file does not exist yet;
 - ``changelog:check`` returns a failing exit code when ``Unreleased`` is empty
   or does not differ from the selected baseline ref;
+- ``changelog:entry --json`` emits the authoring summary as the
+  ``message`` plus structured context describing the file, category, release,
+  optional date, and entry text;
+- ``changelog:check --json`` emits a deterministic JSON payload with
+  ``status``, ``message``, and ``context`` keys for automation consumers;
+- ``changelog:next-version --json`` emits the inferred semantic version
+  as the ``message`` plus structured context describing the inspected changelog
+  path and optional current version;
 - ``changelog:next-version`` uses ``Removed`` or ``Deprecated`` entries for a
   major bump, ``Added`` or ``Changed`` entries for a minor bump, and otherwise
   falls back to a patch bump;
+- ``changelog:promote --json`` emits the promotion summary as the
+  ``message`` plus structured context describing the file, version, and
+  release date written to the changelog;
 - ``changelog:promote`` restores an empty ``Unreleased`` section after
   publishing the requested version;
-- ``changelog:show`` prints only the release body so workflows can feed it
-  directly into GitHub release notes.
+- ``changelog:show`` prints only the release body in text mode so workflows can
+  feed it directly into GitHub release notes;
+- ``changelog:show --json`` emits the rendered release-notes body as the
+  ``message`` plus structured context describing the file, version, and
+  release notes content.
 
 Workflow Integration
 --------------------

docs/commands/changelog.rst

@@ -31,6 +31,16 @@ Options
 ``--fix, -f``
    Automatically fix code style issues. Without this option, ECS runs in dry-run mode.
 
+``--progress``
+   Enable progress output from ECS.
+
+``--json``
+   Emit a structured machine-readable payload instead of the normal terminal
+   output.
+
+``--pretty-json``
+   Emit the same structured payload with indentation for terminal inspection.
+
 Examples
 --------
 
@@ -66,4 +76,8 @@ Behavior
 - Always runs ``composer update --lock --quiet`` first.
 - Composer Normalize runs in ``--dry-run`` mode unless ``--fix`` is specified.
 - ECS uses local ``ecs.php`` when present, otherwise falls back to packaged default.
+- Progress output is disabled by default; use ``--progress`` to re-enable it in
+  text mode.
+- ``--json`` and ``--pretty-json`` forward JSON mode to ECS and suppress its
+  progress bar so the structured payload stays machine-readable.
 - The command executes processes in sequence via ProcessQueue.

docs/commands/code-style.rst

@@ -40,6 +40,13 @@ Options
    Prompt for owners when metadata inference is insufficient and confirm before
    replacing an existing file.
 
+``--json``
+   Emit a structured machine-readable payload instead of the normal terminal
+   output.
+
+``--pretty-json``
+   Emit the same structured payload with indentation for terminal inspection.
+
 Examples
 --------
 

docs/commands/codeowners.rst

@@ -50,6 +50,13 @@ Options
 ``--interactive``
    Prompt before replacing a drifted resource.
 
+``--json``
+   Emit a structured machine-readable payload instead of the normal terminal
+   output.
+
+``--pretty-json``
+   Emit the same structured payload with indentation for terminal inspection.
+
 Examples
 --------
 

docs/commands/copy-resource.rst

@@ -55,6 +55,13 @@ Options
    Asks ``composer-dependency-analyser`` to dump usages for the given package
    or wildcard pattern and enables ``--show-all-usages`` automatically.
 
+``--json``
+   Emit a structured machine-readable payload instead of the normal terminal
+   output.
+
+``--pretty-json``
+   Emit the same structured payload with indentation for terminal inspection.
+
 Examples
 --------