README

Unified Artisan console UX for Laravel: interactive Prompts for humans, deterministic structured guidance for AI agents and CI pipelines.

Requirements

• PHP: ^8.2, ^8.3, or ^8.4
• Laravel (illuminate/console, illuminate/support): ^11.0, ^12.0, or ^13.0

Why Console UX?

Modern Laravel Artisan commands operate in two fundamentally different environments:

1. Human Developers: Sit at interactive TTY terminals and enjoy colorful, searchable, autocompleted prompts via Laravel\Prompts.
2. Autonomous AI Coding Agents & CI Pipelines: Run headless commands (--no-interaction) and need deterministic, fail-fast guidance instead of hanging prompts or ambiguous single-line errors.

alex-kassel/console-ux bridges this gap with a single trait:

• Interactive: Seamlessly delegates to Laravel\Prompts (select, text, confirm).
• Non-Interactive: Fails immediately with structured diagnostics, missing argument highlights, available choices, usage examples, and AI agent remediation notes.
• Machine-Readable: Out-of-the-box --json output rendering.

Installation

Install via Composer:

composer require alex-kassel/console-ux

Usage

Simply use the InteractsWithConsoleUx trait in any Artisan command:

<?php

declare(strict_types=1);

namespace App\Console\Commands;

use AlexKassel\ConsoleUx\Concerns\InteractsWithConsoleUx;
use AlexKassel\ConsoleUx\DTOs\ConsoleUxGuidance;
use Illuminate\Console\Command;

class ScaffoldCommand extends Command
{
    use InteractsWithConsoleUx;

    protected $signature = 'app:scaffold
                            {name? : Entity name to scaffold}
                            {--json : Output machine-readable JSON}';

    public function handle(): int
    {
        $name = $this->argument('name');
        $available = ['model', 'service', 'repository'];

        if (! is_string($name) || trim($name) === '') {
            if ($this->isInteractiveEnvironment()) {
                $name = $this->promptSelect('Choose what to scaffold:', $available);
            } else {
                return $this->failWithGuidance(
                    guidance: 'An entity type is required to scaffold.',
                    argument: 'name',
                    availableOptions: $available,
                    usageExample: 'php artisan app:scaffold model',
                    remediationSteps: ['Select one of the available types.'],
                    agentInstructions: 'Check existing models in app/Models before scaffolding.'
                );
            }
        }

        if ($this->wantsJsonOutput()) {
            return $this->renderJsonResult(['scaffolded' => $name, 'status' => 'success']);
        }

        $this->info("Scaffolded [{$name}] successfully.");

        return self::SUCCESS;
    }
}

Non-Interactive Output Example

When executed with --no-interaction or by an AI agent tool runner without the required argument:

✘ Error: An entity type is required to scaffold.
  Missing Required Argument: name
  Available Options:
    • model
    • service
    • repository
  Usage Example: php artisan app:scaffold model
  Remediation Steps:
    1. Select one of the available types.
  AI Agent Guidance: Check existing models in app/Models before scaffolding.

The agent or CI pipeline immediately understands what was missing, what options are valid, and the exact corrective command to run.

Testing

Run the test suite via PHPUnit:

composer test

Documentation

For full architectural details, see docs/console-ux.md.

License

The MIT License (MIT). Please see License File for more information.