Add Deck workflow automation Nextcloud app

Ports the standalone due-date cron script into a proper Nextcloud 34
app with a personal-settings UI, per-user workflow configuration
(source/target stack, assigned-user and label filters, email
notification), a TimedJob background runner, and Gitea CI pipelines.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

lib/Service/DeckIntegrationService.php

@@ -0,0 +1,230 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OCA\WorkflowDeckAutomation\Service;
+
+use OCA\Deck\Db\Card;
+use OCA\Deck\Db\CardMapper;
+use OCA\Deck\Service\BoardService;
+use OCA\Deck\Service\CardService;
+use OCA\Deck\Service\StackService;
+use OCP\App\IAppManager;
+use OCP\IUser;
+use OCP\Server;
+use Psr\Log\LoggerInterface;
+use Throwable;
+
+/**
+ * Single choke point for everything this app does with Deck.
+ *
+ * Deck's OCA\Deck\* classes are not a documented/stable public API (no
+ * @since markers, no <public> declaration in its info.xml). We use them
+ * directly anyway, per explicit product requirement (no HTTP/OCS calls
+ * against Deck are allowed), but every resolution and call is guarded so a
+ * Deck-side change degrades a single workflow instead of crashing the
+ * whole background run.
+ */
+class DeckIntegrationService {
+	private const DECK_APP_ID = 'deck';
+
+	public function __construct(
+		private IAppManager $appManager,
+		private LoggerInterface $logger,
+	) {
+	}
+
+	public function assertDeckAvailable(IUser $user): void {
+		if (!$this->appManager->isEnabledForUser(self::DECK_APP_ID, $user)) {
+			throw new DeckUnavailableException('Deck is not enabled for user ' . $user->getUID());
+		}
+		if (!class_exists(CardService::class) || !class_exists(BoardService::class) || !class_exists(StackService::class)) {
+			throw new DeckUnavailableException('Deck internal classes are not available');
+		}
+	}
+
+	/**
+	 * @return array<int, array{id: int, title: string}>
+	 */
+	public function listBoardsForCurrentUser(): array {
+		$boards = $this->call(function () {
+			return $this->resolve(BoardService::class)->getUserBoards();
+		}, []);
+
+		return array_map(
+			static fn ($board) => ['id' => $board->getId(), 'title' => $board->getTitle()],
+			$boards,
+		);
+	}
+
+	/**
+	 * @return array<int, array{id: int, title: string}>
+	 */
+	public function listStacks(int $boardId): array {
+		$stacks = $this->call(function () use ($boardId) {
+			return $this->resolve(StackService::class)->findAll($boardId);
+		}, []);
+
+		return array_map(
+			static fn ($stack) => ['id' => $stack->getId(), 'title' => $stack->getTitle()],
+			$stacks,
+		);
+	}
+
+	/**
+	 * @return array<int, array{id: int, title: string, color: string|null}>
+	 */
+	public function listLabels(int $boardId): array {
+		$labels = $this->call(function () use ($boardId) {
+			$board = $this->resolve(BoardService::class)->find($boardId, true);
+			return $board->getLabels() ?? [];
+		}, []);
+
+		return array_map(
+			static fn ($label) => ['id' => $label->getId(), 'title' => $label->getTitle(), 'color' => $label->getColor()],
+			$labels,
+		);
+	}
+
+	/**
+	 * @return array<int, array{uid: string, displayName: string}>
+	 */
+	public function listParticipants(int $boardId): array {
+		$acl = $this->call(function () use ($boardId) {
+			$board = $this->resolve(BoardService::class)->find($boardId, true);
+			return $board->getAcl() ?? [];
+		}, []);
+
+		$participants = [];
+		foreach ($acl as $entry) {
+			$uid = $this->extractParticipantUid($entry);
+			if ($uid !== null && !isset($participants[$uid])) {
+				$participants[$uid] = ['uid' => $uid, 'displayName' => $uid];
+			}
+		}
+
+		return array_values($participants);
+	}
+
+	/**
+	 * Cards in the given stack that are neither archived nor marked done,
+	 * enriched so getAssignedUsers()/getLabels() are populated.
+	 *
+	 * @return Card[]
+	 */
+	public function getActiveCardsInStack(int $stackId): array {
+		return $this->call(function () use ($stackId) {
+			$cardMapper = $this->resolve(CardMapper::class);
+			$cardService = $this->resolve(CardService::class);
+
+			$cards = $cardMapper->findAllByStack($stackId);
+			$cards = $cardService->enrichCards($cards);
+
+			return array_values(array_filter($cards, static function (Card $card) {
+				return !$card->getArchived() && $card->getDone() === null;
+			}));
+		}, []);
+	}
+
+	/**
+	 * @return string[]
+	 */
+	public function getCardAssignedUserIds(Card $card): array {
+		$assigned = $card->getAssignedUsers() ?? [];
+		$uids = [];
+		foreach ($assigned as $entry) {
+			$uid = $this->extractParticipantUid($entry);
+			if ($uid !== null) {
+				$uids[] = $uid;
+			}
+		}
+		return $uids;
+	}
+
+	/**
+	 * @return int[]
+	 */
+	public function getCardLabelIds(Card $card): array {
+		$labels = $card->getLabels() ?? [];
+		$ids = [];
+		foreach ($labels as $label) {
+			if (method_exists($label, 'getId')) {
+				$ids[] = (int)$label->getId();
+			}
+		}
+		return $ids;
+	}
+
+	/**
+	 * Moves a card to another stack using Deck's own reorder logic
+	 * (the exact same code path behind Deck's "move card" action).
+	 */
+	public function moveCard(int $cardId, int $targetStackId): void {
+		$this->call(function () use ($cardId, $targetStackId) {
+			$this->resolve(CardService::class)->reorder($cardId, $targetStackId, 0);
+			return null;
+		}, null, true);
+	}
+
+	/**
+	 * @template T
+	 * @param callable(): T $callback
+	 * @param T $fallback
+	 * @return T
+	 */
+	private function call(callable $callback, mixed $fallback, bool $rethrow = false) {
+		try {
+			return $callback();
+		} catch (DeckUnavailableException $e) {
+			throw $e;
+		} catch (Throwable $e) {
+			$this->logger->error('Deck integration call failed: ' . $e->getMessage(), [
+				'app' => 'workflow_deck_automation',
+				'exception' => $e,
+			]);
+			if ($rethrow) {
+				throw new DeckUnavailableException('Deck call failed: ' . $e->getMessage(), 0, $e);
+			}
+			return $fallback;
+		}
+	}
+
+	/**
+	 * @template T of object
+	 * @param class-string<T> $class
+	 * @return T
+	 */
+	private function resolve(string $class) {
+		if (!class_exists($class)) {
+			throw new DeckUnavailableException("Deck class {$class} does not exist");
+		}
+		return Server::get($class);
+	}
+
+	/**
+	 * Deck's assignment/ACL entries are internal, undocumented value
+	 * objects whose exact accessor shape has changed across versions, so
+	 * we probe the common accessor names defensively instead of relying
+	 * on one fixed method signature.
+	 */
+	private function extractParticipantUid(mixed $entry): ?string {
+		if (is_string($entry)) {
+			return $entry;
+		}
+		if (!is_object($entry)) {
+			return null;
+		}
+		foreach (['getParticipant', 'getUid', 'getParticipantUid', 'getUserId'] as $method) {
+			if (method_exists($entry, $method)) {
+				$value = $entry->$method();
+				if (is_string($value) && $value !== '') {
+					return $value;
+				}
+				if (is_object($value) && method_exists($value, 'getUID')) {
+					return $value->getUID();
+				}
+			}
+		}
+		return null;
+	}
+}