feat(command): add #[Group] and #[SingleInstance] attributes

WebFiori/Cli/Attributes/Group.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+namespace WebFiori\Cli\Attributes;
+
+use Attribute;
+
+/**
+ * Attribute to assign a command to a named group for help display organization.
+ *
+ * @author Ibrahim
+ */
+#[Attribute(Attribute::TARGET_CLASS)]
+class Group {
+    public readonly string $name;
+
+    public function __construct(string $name) {
+        $this->name = $name;
+    }
+}

WebFiori/Cli/Attributes/SingleInstance.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+namespace WebFiori\Cli\Attributes;
+
+use Attribute;
+
+/**
+ * Attribute to prevent concurrent execution of a command.
+ *
+ * When applied to a command class, only one instance of the command
+ * can run at a time. Subsequent attempts will fail with a warning.
+ *
+ * @author Ibrahim
+ */
+#[Attribute(Attribute::TARGET_CLASS)]
+class SingleInstance {
+    public readonly int $exitCode;
+    public readonly ?string $lockPath;
+
+    public function __construct(?string $lockPath = null, int $exitCode = 1) {
+        $this->lockPath = $lockPath;
+        $this->exitCode = $exitCode;
+    }
+}

WebFiori/Cli/Command.php

@@ -45,6 +45,11 @@
      * @var string
      */
     private $description;
+    /**
+     * The group this command belongs to for help display.
+     * @var string|null
+     */
+    private $group;
     /**
      * 
      * @var InputStream
@@ -99,6 +104,7 @@
         }
         $this->aliases = $aliases;
         $this->signalHandlers = [];
+        $this->group = null;
         $this->addArgs($args);
 
         if (!$this->setDescription($description)) {
@@ -379,8 +385,9 @@
      * the method 'Command::exec()'.
      * 
      */
     public function excCommand() : int {
         $retVal = -1;
+        $lockManager = null;
 
         $runner = $this->getOwner();
 
@@ -390,20 +397,45 @@
             }
         }
 
-        if ($this->parseArgsHelper()) {
-            // Check for help first, before validating required arguments
-            if ($this->isArgProvided('help') || $this->isArgProvided('-h')) {
-                $help = $runner->getCommandByName('help');
-                $help->setArgValue('--command', $this->getName());
-                $help->setOwner($runner);
-                $help->setOutputStream($runner->getOutputStream());
-                $this->removeArgument('help');
-
-                return $help->exec();
-            } else if ($this->checkIsArgsSetHelper()) {
-                $retVal = $this->exec();
+        // Check for SingleInstance attribute
+        $singleInstance = $this->resolveSingleInstance();
+
+        if ($singleInstance !== null) {
+            $lockManager = new LockManager();
+
+            if (!$lockManager->acquire($this->getName(), $singleInstance->lockPath)) {
+                $this->warning('Command is already running.');
+
+                if ($runner !== null) {
+                    foreach ($runner->getArgs() as $arg) {
+                        $this->removeArgument($arg->getName());
+                        $arg->resetValue();
+                    }
+                }
+
+                return $singleInstance->exitCode;
             }
+        }
 
+        try {
+            if ($this->parseArgsHelper()) {
+                // Check for help first, before validating required arguments
+                if ($this->isArgProvided('help') || $this->isArgProvided('-h')) {
+                    $help = $runner->getCommandByName('help');
+                    $help->setArgValue('--command', $this->getName());
+                    $help->setOwner($runner);
+                    $help->setOutputStream($runner->getOutputStream());
+                    $this->removeArgument('help');
+
+                    $retVal = $help->exec();
+                } else if ($this->checkIsArgsSetHelper()) {
+                    $retVal = $this->exec();
+                }
+            }
+        } finally {
+            if ($lockManager !== null) {
+                $lockManager->release();
+            }
         }
 
         if ($runner !== null) {
@@ -546,6 +578,15 @@
         return $this->description;
     }
 
+    /**
+     * Returns the group this command belongs to.
+     *
+     * @return string|null The group name, or null if ungrouped.
+     */
+    public function getGroup(): ?string {
+        return $this->group;
+    }
+
     /**
      * Take an input value from the user.
      *
@@ -1100,6 +1141,32 @@
         return $removed;
     }
 
+    /**
+     * Resolves the group for this command from attributes or name convention.
+     *
+     * Priority: 1. Explicit setGroup() 2. #[Group] attribute 3. Colon prefix in name
+     */
+    public function resolveGroup(): void {
+        if ($this->group !== null) {
+            return;
+        }
+
+        $ref = new ReflectionClass($this);
+        $attrs = $ref->getAttributes(Attributes\Group::class);
+
+        if (count($attrs) > 0) {
+            $this->group = $attrs[0]->newInstance()->name;
+
+            return;
+        }
+
+        $colonPos = strpos($this->getName(), ':');
+
+        if ($colonPos !== false) {
+            $this->group = substr($this->getName(), 0, $colonPos);
+        }
+    }
+
     /**
      * Ask the user to select one of multiple values.
      * 
@@ -1214,6 +1281,15 @@
 
         return false;
     }
+
+    /**
+     * Sets the group this command belongs to for help display organization.
+     *
+     * @param string $group The group name.
+     */
+    public function setGroup(string $group): void {
+        $this->group = $group;
+    }
     /**
      * Sets the stream at which the command will read input from.
      * 
@@ -1782,4 +1858,20 @@
 
         return $input;
     }
+
+    /**
+     * Resolves the SingleInstance attribute on this command class.
+     *
+     * @return Attributes\SingleInstance|null The attribute instance, or null if not present.
+     */
+    private function resolveSingleInstance(): ?Attributes\SingleInstance {
+        $ref = new ReflectionClass($this);
+        $attrs = $ref->getAttributes(Attributes\SingleInstance::class);
+
+        if (count($attrs) > 0) {
+            return $attrs[0]->newInstance();
+        }
+
+        return null;
+    }
 }