From 62af4cea9e87f4c4e7f5f1a8b5ba299b11752f98 Mon Sep 17 00:00:00 2001
From: Funky Waddle <paul@funkywaddle.com>
Date: Sat, 21 Feb 2026 19:12:38 -0600
Subject: [PATCH] feat: implement core console interfaces and attributes

---
 src/Attributes/Arg.php                     | 17 +++++
 src/Attributes/Cmd.php                     | 17 +++++
 src/Attributes/HasAttributes.php           | 75 ++++++++++++++++++++++
 src/Attributes/Opt.php                     | 17 +++++
 src/CommandInterface.php                   | 24 +++++++
 src/ConsoleExceptionInterface.php          |  9 +++
 src/ConsoleMiddlewareInterface.php         | 15 +++++
 src/ExitCode.php                           | 19 ++++++
 src/Helpers/MarkdownConverterInterface.php | 12 ++++
 src/Helpers/ProgressBarInterface.php       | 14 ++++
 src/Helpers/TableInterface.php             | 20 ++++++
 src/InputInterface.php                     | 14 ++++
 src/InteractionInterface.php               | 19 ++++++
 src/OutputInterface.php                    | 26 ++++++++
 src/Verbosity.php                          | 14 ++++
 15 files changed, 312 insertions(+)
 create mode 100644 src/Attributes/Arg.php
 create mode 100644 src/Attributes/Cmd.php
 create mode 100644 src/Attributes/HasAttributes.php
 create mode 100644 src/Attributes/Opt.php
 create mode 100644 src/CommandInterface.php
 create mode 100644 src/ConsoleExceptionInterface.php
 create mode 100644 src/ConsoleMiddlewareInterface.php
 create mode 100644 src/ExitCode.php
 create mode 100644 src/Helpers/MarkdownConverterInterface.php
 create mode 100644 src/Helpers/ProgressBarInterface.php
 create mode 100644 src/Helpers/TableInterface.php
 create mode 100644 src/InputInterface.php
 create mode 100644 src/InteractionInterface.php
 create mode 100644 src/OutputInterface.php
 create mode 100644 src/Verbosity.php

diff --git a/src/Attributes/Arg.php b/src/Attributes/Arg.php
new file mode 100644
index 0000000..2b75ec7
--- /dev/null
+++ b/src/Attributes/Arg.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class Arg
+{
+    public function __construct(
+        public string $name,
+        public string $description = ''
+    ) {
+    }
+}
diff --git a/src/Attributes/Cmd.php b/src/Attributes/Cmd.php
new file mode 100644
index 0000000..63d3956
--- /dev/null
+++ b/src/Attributes/Cmd.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+class Cmd
+{
+    public function __construct(
+        public string $name,
+        public string $description = ''
+    ) {
+    }
+}
diff --git a/src/Attributes/HasAttributes.php b/src/Attributes/HasAttributes.php
new file mode 100644
index 0000000..76e6c25
--- /dev/null
+++ b/src/Attributes/HasAttributes.php
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts\Attributes;
+
+use Phred\ConsoleContracts\CommandInterface;
+use ReflectionClass;
+
+/**
+ * Helper trait to surface PHP 8 attributes (Cmd/Arg/Opt) via CommandInterface methods.
+ *
+ * Usage:
+ *   class MyCommand implements CommandInterface { use HasAttributes; ... }
+ *
+ * Note: Methods are provided here; consuming class may override any for custom behavior.
+ */
+trait HasAttributes
+{
+    public function getName(): string
+    {
+        $ref = new ReflectionClass($this);
+        $attr = $ref->getAttributes(Cmd::class)[0] ?? null;
+        if ($attr === null) {
+            return '';
+        }
+        /** @var Cmd $meta */
+        $meta = $attr->newInstance();
+        return $meta->name;
+    }
+
+    public function getDescription(): string
+    {
+        $ref = new ReflectionClass($this);
+        $attr = $ref->getAttributes(Cmd::class)[0] ?? null;
+        if ($attr === null) {
+            return '';
+        }
+        /** @var Cmd $meta */
+        $meta = $attr->newInstance();
+        return $meta->description;
+    }
+
+    /**
+     * @return array<string,string>
+     */
+    public function getArguments(): array
+    {
+        $ref = new ReflectionClass($this);
+        $attrs = $ref->getAttributes(Arg::class);
+        $out = [];
+        foreach ($attrs as $attr) {
+            /** @var Arg $a */
+            $a = $attr->newInstance();
+            $out[$a->name] = $a->description;
+        }
+        return $out;
+    }
+
+    /**
+     * @return array<string,string>
+     */
+    public function getOptions(): array
+    {
+        $ref = new ReflectionClass($this);
+        $attrs = $ref->getAttributes(Opt::class);
+        $out = [];
+        foreach ($attrs as $attr) {
+            /** @var Opt $o */
+            $o = $attr->newInstance();
+            $out[$o->name] = $o->description;
+        }
+        return $out;
+    }
+}
diff --git a/src/Attributes/Opt.php b/src/Attributes/Opt.php
new file mode 100644
index 0000000..226fa05
--- /dev/null
+++ b/src/Attributes/Opt.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class Opt
+{
+    public function __construct(
+        public string $name,
+        public string $description = ''
+    ) {
+    }
+}
diff --git a/src/CommandInterface.php b/src/CommandInterface.php
new file mode 100644
index 0000000..3afca88
--- /dev/null
+++ b/src/CommandInterface.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts;
+
+interface CommandInterface
+{
+    public function getName(): string;
+
+    public function getDescription(): string;
+
+    /**
+     * @return array<string,string> Name => Description
+     */
+    public function getArguments(): array;
+
+    /**
+     * @return array<string,string> Name => Description
+     */
+    public function getOptions(): array;
+
+    public function execute(InputInterface $input, OutputInterface $output): int;
+}
diff --git a/src/ConsoleExceptionInterface.php b/src/ConsoleExceptionInterface.php
new file mode 100644
index 0000000..72aea25
--- /dev/null
+++ b/src/ConsoleExceptionInterface.php
@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts;
+
+interface ConsoleExceptionInterface extends \Throwable
+{
+}
diff --git a/src/ConsoleMiddlewareInterface.php b/src/ConsoleMiddlewareInterface.php
new file mode 100644
index 0000000..c49e814
--- /dev/null
+++ b/src/ConsoleMiddlewareInterface.php
@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts;
+
+interface ConsoleMiddlewareInterface
+{
+    public function handle(
+        CommandInterface $command,
+        InputInterface $input,
+        OutputInterface $output,
+        callable $next
+    ): int;
+}
diff --git a/src/ExitCode.php b/src/ExitCode.php
new file mode 100644
index 0000000..dc0b65a
--- /dev/null
+++ b/src/ExitCode.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts;
+
+final class ExitCode
+{
+    public const OK = 0;            // Successful termination
+    public const FAILURE = 1;       // Generic/legacy failure (non-sysexits)
+    public const USAGE = 64;        // Command line usage error
+    public const DATAERR = 65;      // Data format error
+    public const NOINPUT = 66;      // Cannot open input
+    public const UNAVAILABLE = 69;  // Service unavailable
+    public const SOFTWARE = 70;     // Internal software error
+    public const IOERR = 74;        // Input/output error
+    public const PERM = 77;         // Permission denied
+    public const CONFIG = 78;       // Configuration error
+}
diff --git a/src/Helpers/MarkdownConverterInterface.php b/src/Helpers/MarkdownConverterInterface.php
new file mode 100644
index 0000000..fb37685
--- /dev/null
+++ b/src/Helpers/MarkdownConverterInterface.php
@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts\Helpers;
+
+interface MarkdownConverterInterface
+{
+    public function convert(string $markdown): string;
+
+    public function convertFile(string $path): string;
+}
diff --git a/src/Helpers/ProgressBarInterface.php b/src/Helpers/ProgressBarInterface.php
new file mode 100644
index 0000000..37e0726
--- /dev/null
+++ b/src/Helpers/ProgressBarInterface.php
@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts\Helpers;
+
+interface ProgressBarInterface
+{
+    public function start(int $max = 0): void;
+
+    public function advance(int $step = 1): void;
+
+    public function finish(): void;
+}
diff --git a/src/Helpers/TableInterface.php b/src/Helpers/TableInterface.php
new file mode 100644
index 0000000..bd553c2
--- /dev/null
+++ b/src/Helpers/TableInterface.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts\Helpers;
+
+interface TableInterface
+{
+    /**
+     * @param array<string> $headers
+     */
+    public function setHeaders(array $headers): void;
+
+    /**
+     * @param array<mixed> $row
+     */
+    public function addRow(array $row): void;
+
+    public function render(): void;
+}
diff --git a/src/InputInterface.php b/src/InputInterface.php
new file mode 100644
index 0000000..2923412
--- /dev/null
+++ b/src/InputInterface.php
@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts;
+
+interface InputInterface
+{
+    public function getArgument(string $name, mixed $default = null): mixed;
+
+    public function getOption(string $name, mixed $default = null): mixed;
+
+    public function hasOption(string $name): bool;
+}
diff --git a/src/InteractionInterface.php b/src/InteractionInterface.php
new file mode 100644
index 0000000..30879b1
--- /dev/null
+++ b/src/InteractionInterface.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts;
+
+interface InteractionInterface
+{
+    public function ask(string $question, ?string $default = null): string;
+
+    public function confirm(string $question, bool $default = true): bool;
+
+    public function secret(string $question): string;
+
+    /**
+     * @param array<string|int, mixed> $choices
+     */
+    public function choice(string $question, array $choices, mixed $default = null): mixed;
+}
diff --git a/src/OutputInterface.php b/src/OutputInterface.php
new file mode 100644
index 0000000..37af621
--- /dev/null
+++ b/src/OutputInterface.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts;
+
+interface OutputInterface
+{
+    public function write(string $message): void;
+
+    public function writeln(string $message): void;
+
+    public function success(string $message): void;
+
+    public function info(string $message): void;
+
+    public function error(string $message): void;
+
+    public function warning(string $message): void;
+
+    public function comment(string $message): void;
+
+    public function setVerbosity(int $level): void;
+
+    public function getVerbosity(): int;
+}
diff --git a/src/Verbosity.php b/src/Verbosity.php
new file mode 100644
index 0000000..7cb304f
--- /dev/null
+++ b/src/Verbosity.php
@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phred\ConsoleContracts;
+
+final class Verbosity
+{
+    public const QUIET = 0;
+    public const NORMAL = 1;
+    public const VERBOSE = 2;
+    public const VERY_VERBOSE = 3;
+    public const DEBUG = 4;
+}