monthly-by-day engine + recoreco:run (v0.3)

Asset/css/skeleton.css

@@ -1 +0,0 @@
-/* Skeleton plugin styles -- add CSS here. Loaded via template:layout:css. */

Asset/js/skeleton.js

@@ -1 +0,0 @@
-// Skeleton plugin script -- add JS here. Loaded via template:layout:js.

Console/RecoRecoCommand.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Kanboard\Plugin\RecoReco\Console;
+
+use Kanboard\Console\BaseCommand;
+use Kanboard\Plugin\RecoReco\Model\RecoRecoModel;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * CLI entry point for the RecoReco engine. Run by cron (four times a day from v1.0). Can be run by
+ * hand to test: ./cli recoreco:run
+ */
+class RecoRecoCommand extends BaseCommand
+{
+    protected function configure()
+    {
+        $this
+            ->setName('recoreco:run')
+            ->setDescription('Spawn RecoReco calendar-scheduled cards whose occurrence is due');
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $model = new RecoRecoModel($this->container);
+        $count = $model->run();
+
+        $output->writeln('RecoReco: spawned '.$count.' card(s).');
+
+        return 0;
+    }
+}

Controller/RecurrenceController.php

@@ -0,0 +1,92 @@
+<?php
+
+namespace Kanboard\Plugin\RecoReco\Controller;
+
+use Kanboard\Controller\BaseController;
+use Kanboard\Model\TaskModel;
+
+/**
+ * The "Recurring schedule" modal: configure a card's calendar recurrence and store it in task
+ * metadata. v0.2 is storage only -- no spawning (that is the CLI engine in later versions).
+ *
+ * Gate: a card can only be enabled when it has a due date (the recurrence anchor) and is not
+ * already a native-recurring card (RecoReco and native recurrence are mutually exclusive).
+ */
+class RecurrenceController extends BaseController
+{
+    public function edit(array $values = array(), array $errors = array())
+    {
+        $task = $this->getTask();
+
+        if (empty($values)) {
+            $values = $this->getStoredValues($task);
+        }
+
+        $this->response->html($this->template->render('recoReco:recurrence/edit', array(
+            'task' => $task,
+            'values' => $values,
+            'errors' => $errors,
+            'columns_list' => $this->columnModel->getList($task['project_id']),
+            'frequency_list' => $this->getFrequencyList(),
+            'has_due_date' => ! empty($task['date_due']),
+            'is_native' => $task['recurrence_status'] != TaskModel::RECURRING_STATUS_NONE,
+        )));
+    }
+
+    public function save()
+    {
+        $task = $this->getTask();
+        $input = $this->request->getValues();
+
+        // Only a plain card (has a due date, not native-recurring) may be enabled.
+        $can_recur = ! empty($task['date_due']) && $task['recurrence_status'] == TaskModel::RECURRING_STATUS_NONE;
+        $enabled = ($can_recur && isset($input['recoreco_enabled']) && $input['recoreco_enabled'] == 1) ? 1 : 0;
+
+        $frequency = isset($input['recoreco_frequency']) && array_key_exists($input['recoreco_frequency'], $this->getFrequencyList())
+            ? $input['recoreco_frequency']
+            : 'monthly_day';
+
+        $values = array(
+            'recoreco_enabled' => $enabled,
+            'recoreco_target_column' => isset($input['recoreco_target_column']) ? (int) $input['recoreco_target_column'] : (int) $task['column_id'],
+            'recoreco_frequency' => $frequency,
+            'recoreco_last_day' => isset($input['recoreco_last_day']) ? 1 : 0,
+            'recoreco_days_before' => isset($input['recoreco_days_before']) && ctype_digit((string) $input['recoreco_days_before']) ? (int) $input['recoreco_days_before'] : 0,
+        );
+
+        // Capture the anchor (the due date at enable time) -- the drift-free pattern. The engine
+        // (v0.3) reads it to compute occurrences.
+        if ($enabled) {
+            $values['recoreco_anchor'] = (int) $task['date_due'];
+        }
+
+        $this->taskMetadataModel->save($task['id'], $values);
+        $this->flash->success(t('Recurring schedule saved.'));
+
+        return $this->response->redirect($this->helper->url->to('TaskViewController', 'show', array('task_id' => $task['id'])), true);
+    }
+
+    private function getStoredValues(array $task)
+    {
+        $meta = $this->taskMetadataModel->getAll($task['id']);
+
+        return array(
+            'recoreco_enabled' => isset($meta['recoreco_enabled']) ? (int) $meta['recoreco_enabled'] : 0,
+            'recoreco_target_column' => isset($meta['recoreco_target_column']) ? (int) $meta['recoreco_target_column'] : (int) $task['column_id'],
+            'recoreco_frequency' => isset($meta['recoreco_frequency']) ? $meta['recoreco_frequency'] : 'monthly_day',
+            'recoreco_last_day' => isset($meta['recoreco_last_day']) ? (int) $meta['recoreco_last_day'] : 0,
+            'recoreco_days_before' => isset($meta['recoreco_days_before']) ? (int) $meta['recoreco_days_before'] : 0,
+        );
+    }
+
+    private function getFrequencyList()
+    {
+        return array(
+            'yearly' => t('Yearly'),
+            'monthly_day' => t('Monthly by day'),
+            'monthly_dow' => t('Monthly by weekday'),
+            'weekly' => t('Weekly'),
+            'daily' => t('Daily'),
+        );
+    }
+}

Model/OccurrenceCalculator.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace Kanboard\Plugin\RecoReco\Model;
+
+/**
+ * Pure calendar math for RecoReco.
+ *
+ * Given an anchor due date (the drift-free pattern: day-of-month + time), a frequency, and the
+ * "last day" flag, it computes occurrence datetimes. It has NO container dependencies, so it is
+ * unit-testable in isolation (see Test/OccurrenceCalculatorTest.php).
+ *
+ * Occurrences are always computed from the anchor's day, never by marching a clamped date forward,
+ * so a "30th" schedule goes 30, 28/29, 30, 30... and never drifts to the 28th.
+ *
+ * v0.3 implements monthly-by-day; the other frequencies arrive in v1.1 (occurrenceFrom returns null
+ * for them until then).
+ */
+class OccurrenceCalculator
+{
+    const MAX_MONTHS = 120;
+
+    /**
+     * The earliest occurrence at/after $reference (when $inclusive) or strictly after it.
+     *
+     * @param  int    $anchor     Unix timestamp: the pattern (day-of-month + time).
+     * @param  string $frequency
+     * @param  bool   $lastDay
+     * @param  int    $reference  Unix timestamp.
+     * @param  bool   $inclusive
+     * @return int|null           Occurrence timestamp, or null if the frequency is not yet supported.
+     */
+    public function occurrenceFrom($anchor, $frequency, $lastDay, $reference, $inclusive = false)
+    {
+        switch ($frequency) {
+            case 'monthly_day':
+                return $this->monthlyByDay((int) $anchor, (bool) $lastDay, (int) $reference, (bool) $inclusive);
+            default:
+                return null;
+        }
+    }
+
+    private function monthlyByDay($anchor, $lastDay, $reference, $inclusive)
+    {
+        $anchorDay = (int) date('j', $anchor);
+        $h = (int) date('G', $anchor);
+        $i = (int) date('i', $anchor);
+        $s = (int) date('s', $anchor);
+
+        $y = (int) date('Y', $reference);
+        $m = (int) date('n', $reference);
+
+        for ($k = 0; $k < self::MAX_MONTHS; $k++) {
+            $lastDom = (int) date('t', mktime(0, 0, 0, $m, 1, $y));
+            $day = $lastDay ? $lastDom : min($anchorDay, $lastDom);
+            $occurrence = mktime($h, $i, $s, $m, $day, $y);
+
+            if ($inclusive ? $occurrence >= $reference : $occurrence > $reference) {
+                return $occurrence;
+            }
+
+            $m++;
+            if ($m > 12) {
+                $m = 1;
+                $y++;
+            }
+        }
+
+        return null;
+    }
+}

Model/RecoRecoModel.php

@@ -0,0 +1,170 @@
+<?php
+
+namespace Kanboard\Plugin\RecoReco\Model;
+
+use Kanboard\Core\Base;
+use Kanboard\Model\TaskModel;
+
+/**
+ * The RecoReco engine: find enabled templates and spawn their due occurrences.
+ *
+ * Called by the recoreco:run CLI command. v0.3 handles monthly-by-day and fires everything whose
+ * fire time has arrived (fire time = occurrence - days_before); v1.0 adds the 4-window cron horizon.
+ *
+ * Per template: the native-recurrence yield (decision 13), first-run init / manual-edit re-anchor,
+ * then a catch-up loop that duplicates the card into the target column and advances the cursor.
+ */
+class RecoRecoModel extends Base
+{
+    const CATCHUP_CAP = 24;
+
+    private $calc;
+
+    public function run($now = null)
+    {
+        $now = $now ?: time();
+        $spawned = 0;
+
+        $task_ids = $this->db->table('task_has_metadata')
+            ->eq('name', 'recoreco_enabled')
+            ->eq('value', '1')
+            ->findAllByColumn('task_id');
+
+        foreach ($task_ids as $task_id) {
+            $spawned += $this->processTemplate((int) $task_id, $now);
+        }
+
+        return $spawned;
+    }
+
+    public function processTemplate($task_id, $now)
+    {
+        $task = $this->taskFinderModel->getById($task_id);
+
+        if (empty($task)) {
+            return 0;
+        }
+
+        // Native wins: if the card became native-recurring, RecoReco yields (decision 13).
+        if ($task['recurrence_status'] != TaskModel::RECURRING_STATUS_NONE) {
+            $this->taskMetadataModel->save($task_id, array('recoreco_enabled' => 0));
+            $this->logger->info('RecoReco: disabled on task '.$task_id.' (now native-recurring)');
+            return 0;
+        }
+
+        $meta = $this->taskMetadataModel->getAll($task_id);
+        $frequency = isset($meta['recoreco_frequency']) ? $meta['recoreco_frequency'] : '';
+
+        // v0.3 handles monthly-by-day only; the rest arrive in v1.1.
+        if ($frequency !== 'monthly_day') {
+            return 0;
+        }
+
+        $anchor = isset($meta['recoreco_anchor']) ? (int) $meta['recoreco_anchor'] : 0;
+
+        if ($anchor <= 0) {
+            return 0;
+        }
+
+        $lastDay = isset($meta['recoreco_last_day']) && $meta['recoreco_last_day'] == 1;
+        $daysBefore = isset($meta['recoreco_days_before']) ? (int) $meta['recoreco_days_before'] : 0;
+        $targetColumn = isset($meta['recoreco_target_column']) ? (int) $meta['recoreco_target_column'] : (int) $task['column_id'];
+
+        $cursor = (int) $task['date_due'];
+        $synced = isset($meta['recoreco_synced_due']) ? (int) $meta['recoreco_synced_due'] : null;
+
+        if ($synced === null) {
+            // First run after enabling: place the cursor on the first occurrence.
+            $cursor = $this->firstCursor($anchor, $frequency, $lastDay, $now);
+            $this->setDue($task_id, $cursor);
+        } elseif ($cursor !== $synced) {
+            // The user hand-edited the due date -> re-anchor to it (a reschedule).
+            $anchor = $cursor;
+            $this->taskMetadataModel->save($task_id, array('recoreco_anchor' => $anchor));
+            $this->setDue($task_id, $cursor);
+        }
+
+        // Fire every occurrence whose fire time has arrived, advancing the cursor each time.
+        $spawned = 0;
+        $fireTime = $cursor - $daysBefore * 86400;
+
+        while ($fireTime <= $now && $spawned < self::CATCHUP_CAP) {
+            $this->spawn($task, $targetColumn);
+
+            $next = $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $cursor, false);
+
+            if ($next === null || $next <= $cursor) {
+                break;
+            }
+
+            $cursor = $next;
+            $this->setDue($task_id, $cursor);
+            $fireTime = $cursor - $daysBefore * 86400;
+            $spawned++;
+        }
+
+        return $spawned;
+    }
+
+    /**
+     * The first occurrence: respect an explicitly future anchor (the due date the user set) as the
+     * first one; otherwise jump to the next occurrence on/after now.
+     */
+    private function firstCursor($anchor, $frequency, $lastDay, $now)
+    {
+        if ($anchor >= $now) {
+            return $anchor;
+        }
+
+        return $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $now, true);
+    }
+
+    private function setDue($task_id, $cursor)
+    {
+        // Advance the template's due date directly (no task events) + mirror it for edit detection.
+        $this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => $cursor));
+        $this->taskMetadataModel->save($task_id, array('recoreco_synced_due' => $cursor));
+    }
+
+    private function spawn(array $template, $targetColumn)
+    {
+        // The template's date_due is already the occurrence (setDue), so duplicate() copies it onto
+        // the clone. duplicate() copies fields + tags + links + subtasks, but NO metadata, so the
+        // clone is not a template.
+        $newId = $this->taskDuplicationModel->duplicate($template['id']);
+
+        if ($newId === false) {
+            $this->logger->error('RecoReco: duplicate failed for task '.$template['id']);
+            return false;
+        }
+
+        // duplicate() lands the clone in the source column; move it to the chosen target (top).
+        if ($targetColumn > 0 && $targetColumn != $template['column_id']) {
+            $this->taskPositionModel->movePosition($template['project_id'], $newId, $targetColumn, 1, $template['swimlane_id']);
+        }
+
+        // Reset the "[DUPLICATE]" prefix back to the source title (no events).
+        $this->taskModificationModel->update(array('id' => $newId, 'title' => $template['title']), false);
+
+        // Mark the clone: white icon + cannot itself be made recurring; record its source template.
+        $this->taskMetadataModel->save($newId, array(
+            'recoreco_clone' => 1,
+            'recoreco_source' => $template['id'],
+        ));
+
+        // Signal FinanceBuddy (advance the installment). Harmless no-op if nothing listens.
+        $payload = array('source_task_id' => (int) $template['id'], 'new_task_id' => (int) $newId);
+        $this->hook->reference('recoreco:task:spawned', $payload);
+
+        return $newId;
+    }
+
+    private function calculator()
+    {
+        if ($this->calc === null) {
+            $this->calc = new OccurrenceCalculator();
+        }
+
+        return $this->calc;
+    }
+}

Plugin.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Kanboard\Plugin\Skeleton;
+namespace Kanboard\Plugin\RecoReco;
 
 use Kanboard\Core\Plugin\Base;
 
@@ -8,28 +8,25 @@ class Plugin extends Base
 {
     public function initialize()
     {
-        // 1. Render a visible word at the top of every page (the demo output).
+        // "Recurring schedule" entry in the task Actions sidebar, right after the basic actions
-        $this->template->hook->attach('template:layout:top', 'skeleton:layout/header');
+        // (next to native "Edit recurrence"). Opens the RecoReco config modal.
+        $this->template->hook->attach('template:task:sidebar:after-basic-actions', 'recoReco:task/sidebar_action');
 
-        // 2. Load the plugin stylesheet (currently empty -- proves the CSS hook fires).
+        // The scheduling engine runs from the CLI (cron). Registered CLI-only so web requests do
-        $this->hook->on('template:layout:css', array(
+        // not build the console app.
-            'template' => 'plugins/Skeleton/Asset/css/skeleton.css',
+        if (php_sapi_name() === 'cli') {
-        ));
+            $this->container['cli']->add(new \Kanboard\Plugin\RecoReco\Console\RecoRecoCommand($this->container));
-
+        }
-        // 3. Load the plugin script (currently empty -- proves the JS hook fires).
-        $this->hook->on('template:layout:js', array(
-            'template' => 'plugins/Skeleton/Asset/js/skeleton.js',
-        ));
     }
 
     public function getPluginName()
     {
-        return 'Skeleton';
+        return 'RecoReco';
     }
 
     public function getPluginDescription()
     {
-        return t('Reusable skeleton/template for building Kanboard plugins.');
+        return t('Calendar-scheduled recurring cards: a template card spawns a copy on a date (yearly, monthly, weekly, daily), driven by the card due date.');
     }
 
     public function getPluginAuthor()
@@ -39,12 +36,12 @@ class Plugin extends Base
 
     public function getPluginVersion()
     {
-        return '0.1.0';
+        return '0.3.0';
     }
 
     public function getPluginHomepage()
     {
-        return 'https://code.beco.cc/beco/kanboard-plugin-skeleton';
+        return 'https://code.beco.cc/beco/RecoReco';
     }
 
     public function getCompatibleVersion()

README.md

@@ -1,19 +1,31 @@
-# Skeleton -- a Kanboard plugin template
+# RecoReco -- calendar-scheduled recurring cards
 
-A minimal, working Kanboard plugin that you copy and rename as the starting point for a
+Kanboard's built-in recurrence is event-triggered (a card recurs when you move or close it).
-real plugin. By itself it does only one trivial thing: it renders the word "Skeleton" at
+RecoReco adds **calendar-triggered** recurrence: a card fires on a date, on its own, via cron --
-the top of every page. It changes no data and runs no database migration.
+made for bills, rent, and subscriptions.
 
-## What it demonstrates
+A card marked recurring **stays** as a template; on schedule, RecoReco spawns a plain
+(non-recurring) copy into a column you choose. The template advances to the next date; the copy
+keeps the fired date.
 
-- A complete `Plugin.php` registration class with all the metadata Kanboard shows in
+RecoReco is opt-in per card and inert until you mark a card, so it needs no per-board setting. It
-  Settings -> Plugins (name, description, author, version, homepage, compatible version).
+leaves native recurrence untouched (the two are mutually exclusive per card).
-- A template hook (`template:layout:top`) that injects a template into the page.
+
-- Asset hooks (`template:layout:css` and `template:layout:js`) that load a stylesheet and
+## The idea
-  a script. They are empty for now but prove the injection path works -- handy when a real
+
-  plugin needs custom CSS or JS.
+- **The due date is the anchor.** All timing (day, month, weekday, time) is read from the card's
-- The standard plugin directory layout, with stub folders (`Controller/`, `Model/`,
+  due date -- there are no separate date inputs. A card without a due date cannot be made recurring.
-  `Schema/`, `Locale/`, `Test/`) ready to grow into.
+- **Frequencies:** yearly, monthly by day, monthly by weekday, weekly, daily.
+- **Last day of the month:** an explicit checkbox (honored only when the due date is the last day,
+  or the last such weekday, of its month).
+- **Lead time:** "create the copy N days before the due date", so the card shows up early enough
+  to act on; the copy is still due on the real day.
+
+## Status
+
+Early development. This version adds the **Recurring schedule** modal (a task sidebar action) and
+stores the settings in task metadata. The scheduling engine and the cron command arrive in the
+following versions.
 
 ## Requirements
 
@@ -21,45 +33,9 @@ the top of every page. It changes no data and runs no database migration.
 
 ## Installation
 
-No build step and no dependencies.
+Copy this folder into your Kanboard installation as `plugins/RecoReco/`. The directory name must be
-
+exactly `RecoReco` (Kanboard derives the plugin namespace from the folder name). No build step and
-1. Copy this folder into your Kanboard installation as `plugins/Skeleton/`.
+no database migration.
-2. Reload any page. The word "Skeleton" appears at the top.
-3. Confirm it under Settings -> Plugins.
-
-To uninstall, delete `plugins/Skeleton/`. Nothing else is left behind.
-
-## Directory layout
-
-```
-Skeleton/
-  Plugin.php              Registration and hook wiring (the only required file).
-  README.md
-  LICENSE                 AGPL-3.0.
-  Template/
-    layout/header.php     The visible "Skeleton" word.
-  Asset/
-    css/skeleton.css      Loaded via template:layout:css.
-    js/skeleton.js        Loaded via template:layout:js.
-  Controller/             Stub for future request handlers.
-  Model/                  Stub for future business logic / DB access.
-  Schema/                 Stub for future database migrations.
-  Locale/                 Stub for future translations (e.g. pt_BR/, fr_FR/).
-  Test/                   Stub for future unit tests.
-```
-
-## How to fork this into a new plugin
-
-1. Copy the folder and rename it, e.g. `plugins/MyPlugin/`. The folder name must match the
-   namespace and start with a capital letter.
-2. In `Plugin.php`, change the namespace from `Kanboard\Plugin\Skeleton` to
-   `Kanboard\Plugin\MyPlugin`.
-3. Update the metadata methods (`getPluginName`, `getPluginDescription`, `getPluginAuthor`,
-   `getPluginVersion`, `getPluginHomepage`, `getCompatibleVersion`).
-4. Update the hook target paths: the lowercase prefix in `'skeleton:layout/header'` and the
-   `plugins/Skeleton/Asset/...` asset paths must match the new plugin name.
-5. Replace `Template/layout/header.php` with your real template, or attach to a different
-   hook. See the Kanboard plugin hooks documentation for the full list of hook points.
 
 ## License
 

Template/layout/header.php

@@ -1 +0,0 @@
-<div class="skeleton-plugin-marker">Skeleton</div>

Template/recurrence/edit.php

@@ -0,0 +1,39 @@
+<div class="page-header">
+    <h2><?= t('Recurring schedule') ?><?php if ($has_due_date): ?> <small>(<?= date('Y-m-d H:i', $task['date_due']) ?>)</small><?php endif ?></h2>
+</div>
+
+<?php $can_recur = $has_due_date && ! $is_native ?>
+
+<?php if (! $has_due_date): ?>
+    <p class="alert alert-info"><?= t('Please set a due date first. RecoReco uses the card due date as the recurrence anchor.') ?></p>
+<?php elseif ($is_native): ?>
+    <p class="alert alert-info"><?= t('This card already uses Kanboard built-in recurrence. RecoReco and native recurrence cannot be used together.') ?></p>
+<?php endif ?>
+
+<form method="post" action="<?= $this->url->href('RecurrenceController', 'save', array('plugin' => 'RecoReco', 'task_id' => $task['id'])) ?>" autocomplete="off">
+    <?= $this->form->csrf() ?>
+
+    <?= $this->form->label(t('Make recurring'), 'recoreco_enabled') ?>
+    <div class="recoreco-radios">
+        <label style="display:inline-block; margin-right:16px;">
+            <input type="radio" name="recoreco_enabled" value="0" <?= $values['recoreco_enabled'] == 1 ? '' : 'checked="checked"' ?>> <?= t('No') ?>
+        </label>
+        <label style="display:inline-block; margin-right:16px;">
+            <input type="radio" name="recoreco_enabled" value="1" <?= $values['recoreco_enabled'] == 1 ? 'checked="checked"' : '' ?> <?= $can_recur ? '' : 'disabled="disabled"' ?>> <?= t('Yes') ?>
+        </label>
+    </div>
+
+    <?= $this->form->label(t('Target column (where the copy appears)'), 'recoreco_target_column') ?>
+    <?= $this->form->select('recoreco_target_column', $columns_list, $values) ?>
+
+    <?= $this->form->label(t('Frequency'), 'recoreco_frequency') ?>
+    <?= $this->form->select('recoreco_frequency', $frequency_list, $values) ?>
+
+    <?= $this->form->checkbox('recoreco_last_day', t('Last day of the month (honored only when the due date is the last day / last weekday of its month)'), 1, $values['recoreco_last_day'] == 1) ?>
+
+    <?= $this->form->label(t('Create the copy this many days before the due date'), 'recoreco_days_before') ?>
+    <input type="number" name="recoreco_days_before" min="0" value="<?= $this->text->e($values['recoreco_days_before']) ?>">
+
+
+    <?= $this->modal->submitButtons() ?>
+</form>

Template/task/sidebar_action.php

@@ -0,0 +1,3 @@
+<li>
+    <?= $this->modal->medium('calendar', t('Recurring schedule'), 'RecurrenceController', 'edit', array('plugin' => 'RecoReco', 'task_id' => $task['id'])) ?>
+</li>

Test/OccurrenceCalculatorTest.php

@@ -0,0 +1,103 @@
+<?php
+
+/*
+ * Standalone test for the RecoReco date math -- no Kanboard / PHPUnit harness needed.
+ * Run with:  php Test/OccurrenceCalculatorTest.php
+ *
+ * OccurrenceCalculator is pure, so this exercises the highest-risk correctness surface (month
+ * lengths, leap years, the last-day rule, the drift-free clamp).
+ */
+
+require __DIR__.'/../Model/OccurrenceCalculator.php';
+
+use Kanboard\Plugin\RecoReco\Model\OccurrenceCalculator;
+
+date_default_timezone_set('UTC');
+
+$calc = new OccurrenceCalculator();
+$failures = 0;
+
+function ts($str)
+{
+    return strtotime($str.' UTC');
+}
+
+function check($label, $got, $expected, &$failures)
+{
+    $ok = $got === $expected;
+    $g = $got === null ? 'null' : date('Y-m-d H:i', $got);
+    $e = $expected === null ? 'null' : date('Y-m-d H:i', $expected);
+    echo ($ok ? 'PASS' : 'FAIL').'  '.$label.'  got='.$g.'  expected='.$e."\n";
+    if (! $ok) {
+        $failures++;
+    }
+}
+
+// 1. Plain day-of-month: the 15th, every month.
+check(
+    'monthly 15th, next after Jan 20',
+    $calc->occurrenceFrom(ts('2023-01-15 10:30'), 'monthly_day', false, ts('2023-01-20 00:00'), false),
+    ts('2023-02-15 10:30'),
+    $failures
+);
+
+// 2. Drift-free clamp: the 30th -> Feb clamps to 28 -> back to 30 in March (NOT 28).
+check(
+    '30th -> Feb (non-leap) clamps to 28',
+    $calc->occurrenceFrom(ts('2023-01-30 09:00'), 'monthly_day', false, ts('2023-01-30 09:00'), false),
+    ts('2023-02-28 09:00'),
+    $failures
+);
+check(
+    '30th -> March returns to 30 (no drift)',
+    $calc->occurrenceFrom(ts('2023-01-30 09:00'), 'monthly_day', false, ts('2023-02-28 09:00'), false),
+    ts('2023-03-30 09:00'),
+    $failures
+);
+
+// 3. Last-day rule: last day of each month.
+check(
+    'last-day: Jan 31 -> Feb 28 (non-leap)',
+    $calc->occurrenceFrom(ts('2023-01-31 08:00'), 'monthly_day', true, ts('2023-01-31 08:00'), false),
+    ts('2023-02-28 08:00'),
+    $failures
+);
+check(
+    'last-day: Feb -> March 31',
+    $calc->occurrenceFrom(ts('2023-01-31 08:00'), 'monthly_day', true, ts('2023-02-28 08:00'), false),
+    ts('2023-03-31 08:00'),
+    $failures
+);
+
+// 4. Leap year: last day of Feb 2024 is the 29th.
+check(
+    'last-day: Feb 2024 -> 29th (leap)',
+    $calc->occurrenceFrom(ts('2024-01-31 08:00'), 'monthly_day', true, ts('2024-02-01 00:00'), false),
+    ts('2024-02-29 08:00'),
+    $failures
+);
+
+// 5. Inclusive vs exclusive at an exact occurrence.
+check(
+    'inclusive returns the same instant',
+    $calc->occurrenceFrom(ts('2023-03-10 12:00'), 'monthly_day', false, ts('2023-03-10 12:00'), true),
+    ts('2023-03-10 12:00'),
+    $failures
+);
+check(
+    'exclusive skips to next month',
+    $calc->occurrenceFrom(ts('2023-03-10 12:00'), 'monthly_day', false, ts('2023-03-10 12:00'), false),
+    ts('2023-04-10 12:00'),
+    $failures
+);
+
+// 6. Unsupported frequency (until v1.1) returns null.
+check(
+    'weekly not supported yet -> null',
+    $calc->occurrenceFrom(ts('2023-03-10 12:00'), 'weekly', false, ts('2023-03-10 12:00'), false),
+    null,
+    $failures
+);
+
+echo "\n".($failures === 0 ? 'ALL PASSED' : $failures.' FAILURE(S)')."\n";
+exit($failures === 0 ? 0 : 1);

VERSION

@@ -1 +1 @@
-RecoReco v0.1
+RecoReco v0.3