Adds an --agentic-run option

Author: raphaelstolt

.gitattributes

@@ -14,6 +14,7 @@ bin/release-version export-ignore
 bin/start-watchman export-ignore
 box.json.dist export-ignore
 CHANGELOG.md export-ignore
+CLAUDE.md export-ignore
 example/ export-ignore
 Formula/ export-ignore
 LICENSE.md export-ignore

CLAUDE.md

@@ -0,0 +1,56 @@
+# Lean Package Validator
+
+A PHP CLI tool that validates whether a project's `.gitattributes` file is correctly configured to exclude development 
+artifacts from release archives.
+
+## Tech Stack
+
+- **PHP 8.1+** with `declare(strict_types=1)` on all files
+- **Symfony Console** for the CLI framework
+- **PHPUnit 11** for testing
+- **PHPStan level 8** for static analysis
+- **PHP-CS-Fixer** (PSR-2/PSR-12) for code style
+
+## Commands
+
+```bash
+# Run tests
+composer lpv:test
+
+# Run tests with coverage
+composer lpv:test-with-coverage
+
+# Fix code style
+composer lpv:cs-fix
+
+# Lint code style (check only)
+composer lpv:cs-lint
+
+# Static analysis
+composer lpv:static-analyse
+
+# All pre-commit checks
+composer lpv:pre-commit-check
+
+# Spell check
+composer lpv:spell-check
+
+# Dependency analysis
+composer lpv:dependency-analyse
+```
+
+## Project Structure
+
+- `bin/lean-package-validator` — CLI entry point
+- `src/Commands/` — CLI command classes
+- `src/Presets/` — Language presets (PHP, Python, Go, JavaScript, Rust)
+- `src/` — Core classes (Analyser, Archive, Glob, Tree, etc.)
+- `tests/` — PHPUnit test suite mirroring `src/` structure
+- `resources/boost/skills/` — AI assistant skills
+
+## Conventions
+
+- Namespace root: `Stolt\LeanPackage\`
+- PSR-4 autoloading, one class per file
+- Full type hints on all method parameters and return types
+- Tests use `Stolt\LeanPackage\Tests\` namespace

README.md

@@ -336,6 +336,34 @@ This project [includes](./resources/boost/skills) three AI skills focused on man
 - __create__: generate a `.gitattributes` file when it is missing.
 - __update__: reconcile an existing `.gitattributes` file with expected export-ignore rules.
 
+### Agentic-friendly output
+
+All commands support the `--agentic-run` option, which switches the output from human-readable text to a structured JSON object. This is useful when integrating the tool into AI workflows or automation pipelines where machine-readable output is preferred.
+
+``` bash
+lean-package-validator validate --agentic-run [<directory>]
+```
+
+``` json
+{
+    "command": "validate",
+    "status": "success",
+    "message": "The .gitattributes file is considered valid.",
+    "valid": true
+}
+```
+
+Each response always includes `command`, `status` (`success` or `failure`), and `message` fields. Commands also include additional context-specific fields:
+
+| Command    | Additional fields on success                          |
+|------------|-------------------------------------------------------|
+| `validate` | `valid`, `warnings` (if any), `expected_gitattributes_content` (on failure), `archive_valid`, `unexpected_artifacts` |
+| `create`   | `gitattributes_file_path`                             |
+| `update`   | `gitattributes_file_path`                             |
+| `init`     | `lpv_file_path`                                       |
+| `refresh`  | `lpv_file_path`                                       |
+| `tree`     | `package`, `tree`                                     |
+
 ### Running tests
 
 ``` bash

src/Commands/Concerns/OutputOptions.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Stolt\LeanPackage\Commands\Concerns;
+
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+trait OutputOptions
+{
+    protected function addAgenticOutputOption(callable $addOption): void
+    {
+        $addOption('agentic-run', null, InputOption::VALUE_NONE, 'Enable agentic-friendly output formatting');
+    }
+
+    protected function isAgenticRun(InputInterface $input): bool
+    {
+        return (bool) $input->getOption('agentic-run');
+    }
+
+    /**
+     * @param array<string, mixed> $extra
+     */
+    protected function writeAgenticOutput(
+        OutputInterface $output,
+        string $command,
+        bool $success,
+        string $message,
+        array $extra = []
+    ): void {
+        $data = \array_merge(
+            ['command' => $command, 'status' => $success ? 'success' : 'failure', 'message' => $message],
+            $extra
+        );
+        $output->writeln((string) \json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+    }
+}

src/Commands/CreateCommand.php

@@ -6,6 +6,7 @@
 
 use Stolt\LeanPackage\Analyser;
 use Stolt\LeanPackage\Commands\Concerns\GeneratesGitattributesOptions;
+use Stolt\LeanPackage\Commands\Concerns\OutputOptions;
 use Stolt\LeanPackage\GitattributesFileRepository;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputArgument;
@@ -16,6 +17,7 @@
 final class CreateCommand extends Command
 {
     use GeneratesGitattributesOptions;
+    use OutputOptions;
 
     /**
      * @var string $defaultName
@@ -53,12 +55,16 @@ protected function configure(): void
             InputOption::VALUE_NONE,
             'Do not write any files. Output the expected .gitattributes content'
         ));
+        $this->addAgenticOutputOption(function (...$args) {
+            $this->getDefinition()->addOption(new InputOption(...$args));
+        });
     }
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
         $directory = (string) $input->getArgument('directory') ?: \getcwd();
         $this->analyser->setDirectory($directory);
+        $isAgenticRun = $this->isAgenticRun($input);
 
         // Apply options that influence generation
         if (!$this->applyGenerationOptions($input, $output, $this->analyser)) {
@@ -68,16 +74,24 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $gitattributesPath = $this->analyser->getGitattributesFilePath();
 
         if (\file_exists($gitattributesPath) && $input->getOption('dry-run') !== true) {
-            $output->writeln('A .gitattributes file already exists. Use the update command to modify it.');
-
+            $message = 'A .gitattributes file already exists. Use the update command to modify it.';
+            if ($isAgenticRun) {
+                $this->writeAgenticOutput($output, 'create', false, $message);
+            } else {
+                $output->writeln($message);
+            }
             return self::FAILURE;
         }
 
         $expected = $this->analyser->getExpectedGitattributesContent();
 
         if ($expected === '') {
-            $output->writeln('Unable to determine expected .gitattributes content for the given directory.');
-
+            $message = 'Unable to determine expected .gitattributes content for the given directory.';
+            if ($isAgenticRun) {
+                $this->writeAgenticOutput($output, 'create', false, $message);
+            } else {
+                $output->writeln($message);
+            }
             return self::FAILURE;
         }
 
@@ -91,14 +105,22 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         try {
             $this->repository->createGitattributesFile($expected);
         } catch (\Throwable $e) {
-            $output->writeln('Creation of .gitattributes file failed.');
-
+            $message = 'Creation of .gitattributes file failed.';
+            if ($isAgenticRun) {
+                $this->writeAgenticOutput($output, 'create', false, $message);
+            } else {
+                $output->writeln($message);
+            }
             return self::FAILURE;
         }
 
         $directory = \realpath($directory);
-        $output->writeln("A .gitattributes file has been created in {$directory}.");
-
+        $message = "A .gitattributes file has been created in {$directory}.";
+        if ($isAgenticRun) {
+            $this->writeAgenticOutput($output, 'create', true, $message, ['gitattributes_file_path' => $gitattributesPath]);
+        } else {
+            $output->writeln($message);
+        }
         return self::SUCCESS;
     }
 }

src/Commands/InitCommand.php

@@ -5,6 +5,7 @@
 namespace Stolt\LeanPackage\Commands;
 
 use Stolt\LeanPackage\Analyser;
+use Stolt\LeanPackage\Commands\Concerns\OutputOptions;
 use Stolt\LeanPackage\Exceptions\PresetNotAvailable;
 use Stolt\LeanPackage\Presets\CommonPreset;
 use Stolt\LeanPackage\Presets\Finder;
@@ -16,6 +17,8 @@
 
 final class InitCommand extends Command
 {
+    use OutputOptions;
+
     private const DEFAULT_PRESET = 'PHP';
 
     /**
@@ -82,6 +85,9 @@ protected function configure(): void
             InputOption::VALUE_NONE,
             'Do not write any files. Output the content that would be written'
         ));
+        $this->addAgenticOutputOption(function (...$args) {
+            $this->getDefinition()->addOption(new InputOption(...$args));
+        });
     }
 
     /**
@@ -99,16 +105,19 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $overwriteDefaultLpvFile = $input->getOption('overwrite');
         $chosenPreset = (string) $input->getOption('preset');
         $globPatternFromPreset = false;
+        $isAgenticRun = $this->isAgenticRun($input);
 
         if ($directory !== WORKING_DIRECTORY) {
             try {
                 $this->analyser->setDirectory($directory);
             } catch (\RuntimeException $e) {
                 $warning = "Warning: The provided directory "
                     . "'$directory' does not exist or is not a directory.";
-                $outputContent = '<error>' . $warning . '</error>';
-                $output->writeln($outputContent);
-
+                if ($isAgenticRun) {
+                    $this->writeAgenticOutput($output, 'init', false, $warning);
+                } else {
+                    $output->writeln('<error>' . $warning . '</error>');
+                }
                 $output->writeln($e->getMessage(), OutputInterface::VERBOSITY_DEBUG);
 
                 return Command::FAILURE;
@@ -122,9 +131,11 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
         if (\file_exists($defaultLpvFile) && $overwriteDefaultLpvFile === false) {
             $warning = 'Warning: A default .lpv file already exists.';
-            $outputContent = '<error>' . $warning . '</error>';
-            $output->writeln($outputContent);
-
+            if ($isAgenticRun) {
+                $this->writeAgenticOutput($output, 'init', false, $warning);
+            } else {
+                $output->writeln('<error>' . $warning . '</error>');
+            }
             return Command::FAILURE;
         }
 
@@ -135,9 +146,11 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $defaultGlobPattern = $this->finder->getPresetGlobByLanguageName($chosenPreset);
         } else {
             $warning = 'Warning: Chosen preset ' . $chosenPreset . ' is not available. Maybe contribute it?.';
-            $outputContent = '<error>' . $warning . '</error>';
-            $output->writeln($outputContent);
-
+            if ($isAgenticRun) {
+                $this->writeAgenticOutput($output, 'init', false, $warning);
+            } else {
+                $output->writeln('<error>' . $warning . '</error>');
+            }
             return Command::FAILURE;
         }
 
@@ -164,14 +177,22 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
         if ($bytesWritten === false) {
             $warning = 'Warning: The creation of the default .lpv file failed.';
-            $outputContent = '<error>' . $warning . '</error>';
-            $output->writeln($outputContent);
+            if ($isAgenticRun) {
+                $this->writeAgenticOutput($output, 'init', false, $warning);
+            } else {
+                $output->writeln('<error>' . $warning . '</error>');
+            }
 
             return Command::FAILURE;
         }
 
-        $info = "<info>Created default '$defaultLpvFile' file.</info>";
-        $output->writeln($info);
+        $message = "Created default '$defaultLpvFile' file.";
+
+        if ($isAgenticRun) {
+            $this->writeAgenticOutput($output, 'init', true, $message, ['lpv_file_path' => $defaultLpvFile]);
+        } else {
+            $output->writeln("<info>{$message}</info>");
+        }
 
         return Command::SUCCESS;
     }