v1.4 backfill-to-today algorithm, 12-card cap, idempotent spawns; drop dual-path

Controller/ConfigController.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Kanboard\Plugin\RecoReco\Controller;
+
+use Kanboard\Controller\BaseController;
+use Kanboard\Plugin\RecoReco\Model\RecoRecoModel;
+
+/**
+ * Global settings page for RecoReco.
+ *
+ * Admin-only for free: the application ACL is keyed by the SHORT controller name, and core maps
+ * 'ConfigController' => APP_ADMIN (AuthenticationProvider::getApplicationAccessMap), so every action
+ * on a controller named ConfigController requires an application administrator -- plugin included.
+ * Keep admin-only actions in THIS controller; a differently-named controller would default to
+ * APP_USER (any logged-in user).
+ */
+class ConfigController extends BaseController
+{
+    public function show()
+    {
+        $this->response->html($this->helper->layout->config('recoReco:config/show', array(
+            'title' => t('Settings').' &gt; '.t('RecoReco'),
+        )));
+    }
+
+    /**
+     * Run the scheduler now -- the same pass cron runs: spawn every template card whose occurrence
+     * is due, across all boards. Idempotent (an occurrence is never spawned twice), so it is safe to
+     * trigger at any time.
+     */
+    public function run()
+    {
+        $this->checkCSRFForm();
+
+        $count = (new RecoRecoModel($this->container))->run();
+
+        $this->flash->success(t('RecoReco: spawned %d card(s).', $count));
+        $this->response->redirect($this->helper->url->to('ConfigController', 'show', array('plugin' => 'RecoReco')));
+    }
+}

Model/RecoRecoModel.php

@@ -8,15 +8,34 @@ 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.
+ * Called by the recoreco:run CLI command (from cron, or from the identical "Run now" button). One
+ * run is one pass over every enabled template; running it five times a day instead of four is
+ * harmless -- see the idempotency note below.
  *
- * 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.
+ * Per template there is a SINGLE algorithm (no first-run vs catch-up split):
+ *
+ *   1. Yield to native recurrence if the card became native-recurring (decision 13).
+ *   2. Walk occurrences forward from the cursor (the template due date), collecting every one whose
+ *      fire time (occurrence - days_before) has arrived (before this run's horizon). The first
+ *      occurrence still ahead of the horizon is the "next future" one.
+ *   3. Cap to the most recent MAX_BACKFILL: if more than that are due (a template set far in the
+ *      past), skip the OLDEST overflow and keep the newest ones -- contiguous, no gap.
+ *   4. Spawn each kept occurrence into the target column, dated to that occurrence.
+ *   5. Park the cursor on the next future occurrence and stop.
+ *
+ * Idempotency: after a run the cursor sits on a future occurrence, so a second run the same day
+ * collects nothing. As a belt-and-suspenders guard against a run overlapping cron on the same
+ * occurrence, spawn() is skipped when a clone for that (template, due) already exists (cloneExists).
  */
 class RecoRecoModel extends Base
 {
-    const CATCHUP_CAP = 24;
+    // Most recent occurrences to actually spawn in one run. A template set far in the past spawns
+    // these newest ones and skips the older overflow (no gap), rather than flooding the board.
+    const MAX_BACKFILL = 12;
+
+    // Safety bound on the occurrence walk so a misbehaving calculator can never loop forever
+    // (1200 monthly steps is a century).
+    const MAX_ITERATIONS = 1200;
 
     private $calc;
 
@@ -43,7 +62,7 @@ class RecoRecoModel extends Base
      * "ceil now to the next 6h boundary, then +12h", which lands on the four daily runs:
      * 05:58 -> 18:00, 11:58 -> 00:00, 17:58 -> 06:00, 23:58 -> 12:00. Gives a 12h look-ahead with a
      * 6h overlap between runs, so a missed run is covered by its neighbour. Past-due occurrences are
-     * naturally included (their fire time is < now < horizon) -- that is the catch-up.
+     * naturally included (their fire time is < now < horizon) -- that is the back-fill.
      *
      * @param  int $now
      * @return int
@@ -79,6 +98,8 @@ class RecoRecoModel extends Base
             return 0;
         }
 
+        // The anchor defines the recurrence PATTERN (which day-of-month, which weekday ordinal); the
+        // cursor (the template due date) is our POSITION in that pattern.
         $anchor = isset($meta['recoreco_anchor']) ? (int) $meta['recoreco_anchor'] : 0;
 
         if ($anchor <= 0) {
@@ -91,46 +112,83 @@ class RecoRecoModel extends Base
         // Default off: only keep the duplicate link when explicitly turned on.
         $linkCopies = isset($meta['recoreco_link_copies']) && $meta['recoreco_link_copies'] == 1;
 
+        // Phase 1 -- walk forward from the cursor, collecting every occurrence whose fire time has
+        // arrived. The loop exits on the first occurrence still ahead of the horizon, which is then
+        // the "next future" one to park on.
         $cursor = (int) $task['date_due'];
-        $synced = isset($meta['recoreco_synced_due']) ? (int) $meta['recoreco_synced_due'] : null;
+        $due = array();
+        $iterations = 0;
 
-        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 is before this run's horizon (this includes
-        // past-due ones -> catch-up), advancing the cursor each time.
-        $spawned = 0;
-        $fireTime = $cursor - $daysBefore * 86400;
-
-        while ($fireTime < $horizon && $spawned < self::CATCHUP_CAP) {
-            $this->spawn($task, $targetColumn);
+        while ($cursor - $daysBefore * 86400 < $horizon && $iterations < self::MAX_ITERATIONS) {
+            $due[] = $cursor;
 
             $next = $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $cursor, false);
 
             if ($next === null || $next <= $cursor) {
-                break;
+                break; // calculator cannot advance -- stop rather than loop
             }
 
             $cursor = $next;
-            $this->setDue($task_id, $cursor);
-            $fireTime = $cursor - $daysBefore * 86400;
+            $iterations++;
+        }
+
+        $nextFuture = $cursor;
+
+        // Phase 2 -- cap to the most recent MAX_BACKFILL, skipping the oldest overflow (no gap).
+        $skip = max(0, count($due) - self::MAX_BACKFILL);
+        $toSpawn = array_slice($due, $skip);
+
+        // Phase 3 -- spawn each kept occurrence, dated to that occurrence. Idempotent: skip any that
+        // this template has already spawned (survives a run overlapping cron on the same occurrence).
+        $spawned = 0;
+
+        foreach ($toSpawn as $occurrence) {
+            if ($this->cloneExists($task_id, $occurrence)) {
+                continue;
+            }
+
+            // duplicate() copies the template's date_due onto the clone, so set it to this occurrence
+            // first, then spawn.
+            $this->setDue($task_id, $occurrence);
+            $this->spawn($task, $targetColumn);
             $spawned++;
         }
 
+        // Phase 4 -- park the cursor on the next future occurrence and stop.
+        $this->setDue($task_id, $nextFuture);
+
         // Reconcile the duplicate links with the setting (removes both new and old ones when off).
         $this->syncCloneLinks($task_id, $linkCopies);
 
         return $spawned;
     }
 
+    /**
+     * Has this template already spawned a clone for the given occurrence? A clone records its source
+     * template (recoreco_source) and carries the occurrence as its due date, so the pair identifies
+     * it. This makes a repeated or overlapping run idempotent -- an occurrence is never spawned twice.
+     *
+     * @param  int $template_id
+     * @param  int $due
+     * @return bool
+     */
+    private function cloneExists($template_id, $due)
+    {
+        $clone_ids = $this->db->table('task_has_metadata')
+            ->eq('name', 'recoreco_source')
+            ->eq('value', (string) $template_id)
+            ->findAllByColumn('task_id');
+
+        if (empty($clone_ids)) {
+            return false;
+        }
+
+        return $this->db->table(TaskModel::TABLE)
+            ->in('id', $clone_ids)
+            ->eq('date_due', $due)
+            ->exists();
+    }
+
     /**
      * Reconcile a template's "is a duplicate of" links with the link-copies setting. When off, remove
      * the links to THIS template's own RecoReco clones (identified by recoreco_source, so manual
@@ -154,24 +212,10 @@ class RecoRecoModel extends Base
         }
     }
 
-    /**
-     * 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)
+    private function setDue($task_id, $due)
     {
-        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));
+        // Move the template's due date directly (no task events fired). This is the cursor.
+        $this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => $due));
     }
 
     private function spawn(array $template, $targetColumn)

Plugin.php

@@ -20,6 +20,10 @@ class Plugin extends Base
         // Board card icon: black on a recurring template, white (inverse) on a generated copy.
         $this->template->hook->attach('template:board:task:icons', 'recoReco:board/task_icon');
 
+        // Global settings page (Settings -> RecoReco) with a manual "Run now" button that triggers
+        // the same scheduler pass as cron. Admin-only for free via the shared 'ConfigController' ACL.
+        $this->template->hook->attach('template:config:sidebar', 'recoReco:config/sidebar');
+
         // The scheduling engine runs from the CLI (cron). Registered CLI-only so web requests do
         // not build the console app.
         if (php_sapi_name() === 'cli') {
@@ -51,7 +55,7 @@ class Plugin extends Base
 
     public function getPluginVersion()
     {
-        return '1.2.0';
+        return '1.4.0';
     }
 
     public function getPluginHomepage()

README.md

@@ -31,15 +31,24 @@ The engine runs from the CLI command `recoreco:run`. Add it to cron **four times
 ```
 
 (Point the path at your install and run it as the user that owns Kanboard's data.) Each run looks
-ahead 12 hours; the runs overlap by 6 hours, so a single missed run is covered by the next one, and
-any occurrence whose time is already past is still caught up. `days before` shifts a copy earlier
-within that lead. You can also run it by hand any time: `php cli recoreco:run`.
+ahead 12 hours; the runs overlap by 6 hours, so a single missed run is covered by the next one.
+
+Each run walks a template forward from its current due date and spawns **every** occurrence whose
+fire time has arrived -- so occurrences already in the past are backfilled, not skipped. To avoid
+flooding the board when a template was set far in the past, a single run spawns at most the **12
+most recent** due occurrences; any older overflow is skipped (contiguous, no gap) and the template
+advances straight to the next future occurrence. `days before` shifts a copy earlier within the
+lead. Runs are idempotent: an occurrence is never spawned twice, so running an extra time is safe.
+
+You can trigger the exact same pass by hand -- either on the CLI (`php cli recoreco:run`) or with
+the **Run now** button under **Settings -> RecoReco** (admin only). The button and cron do the
+identical thing.
 
 ## Status
 
-Working for **monthly by day** (with the last-day rule), driven by cron. The remaining frequencies
-(yearly, weekly, daily, monthly by weekday), the recurrence icons, and the FinanceBuddy
-installment hand-off arrive in the following versions.
+All five frequencies work (yearly, monthly by day, monthly by weekday, weekly, daily) with the
+last-day rule, board recurrence icons, backfill with the 12-occurrence cap, the Run-now button, and
+the FinanceBuddy installment hand-off.
 
 ## Requirements
 

Template/config/show.php

@@ -0,0 +1,14 @@
+<div class="page-header">
+    <h2><?= t('RecoReco') ?></h2>
+</div>
+
+<p class="form-help">
+    <?= t('Run the recurring-card scheduler now. This spawns every template card whose occurrence is due, on all boards -- the same pass the cron job runs. It is safe to run at any time: an occurrence is never spawned twice.') ?>
+</p>
+
+<form method="post" action="<?= $this->url->href('ConfigController', 'run', array('plugin' => 'RecoReco')) ?>">
+    <?= $this->form->csrf() ?>
+    <div class="form-actions">
+        <button type="submit" class="btn btn-blue"><?= t('Run now') ?></button>
+    </div>
+</form>

Template/config/sidebar.php

@@ -0,0 +1,3 @@
+<li <?= $this->app->checkMenuSelection('ConfigController', 'show', 'RecoReco') ?>>
+    <?= $this->url->link(t('RecoReco'), 'ConfigController', 'show', array('plugin' => 'RecoReco')) ?>
+</li>

VERSION

@@ -1 +1 @@
-RecoReco v1.2
+RecoReco v1.4