Integrations hardening -- Set up dimmed off RecoReco/FinanceBuddy; honest Disable (v0.6.0)

Asset/css/qualkard.css

@@ -0,0 +1,18 @@
+/* QualKard mastery badge (under the card title on the board). */
+.qk-line {
+    margin-top: 2px;
+}
+
+.qk-badge {
+    display: inline-block;
+    padding: 0 6px;
+    border-radius: 3px;
+    color: #fff;
+    font-size: 0.85em;
+    font-weight: bold;
+}
+
+.qk-new  { background: #e6b800; } /* unread */
+.qk-low  { background: #c0392b; } /* < 50% */
+.qk-mid  { background: #27ae60; } /* 50-89% */
+.qk-high { background: #2980b9; } /* >= 90% */

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.

Controller/QualKardController.php

@@ -0,0 +1,99 @@
+<?php
+
+namespace Kanboard\Plugin\QualKard\Controller;
+
+use Kanboard\Controller\BaseController;
+use Kanboard\Core\Controller\AccessForbiddenException;
+use Kanboard\Plugin\QualKard\Helper\QualKardHelper;
+
+/**
+ * QualKard board actions, posted from the project Integrations page: set up the study board, reset
+ * all cards, or disable. Project-manager gated (the restructure is destructive).
+ */
+class QualKardController extends BaseController
+{
+    /**
+     * Turn this project into a study board: rename the first 7 columns to the standard names (create
+     * or delete to reach exactly 7), move every card to Drafts, store the column roles, reset all
+     * cards to unread + armed-inert, and enable. Once-per-conversion, explicit + confirmed.
+     */
+    public function setup()
+    {
+        $project = $this->authorize();
+        $helper = new QualKardHelper($this->container);
+
+        $names = array('Drafts', 'Study', 'Hairy', 'Hard', 'Medium', 'Easy', 'Done');
+        $columns = $this->columnModel->getAll($project['id']); // position-ordered rows
+        $ids = array();
+
+        for ($i = 0; $i < 7; $i++) {
+            if (isset($columns[$i])) {
+                $this->columnModel->update($columns[$i]['id'], $names[$i]);
+                $ids[$i] = (int) $columns[$i]['id'];
+            } else {
+                $ids[$i] = (int) $this->columnModel->create($project['id'], $names[$i]);
+            }
+        }
+
+        // Move every card to Drafts BEFORE deleting extras -- remove() is a raw DELETE (tasks cascade).
+        foreach ($this->taskFinderModel->getAll($project['id']) as $task) {
+            $this->taskPositionModel->movePosition($project['id'], $task['id'], $ids[0], 1, $task['swimlane_id'], false);
+        }
+
+        for ($i = 7, $n = count($columns); $i < $n; $i++) {
+            $this->columnModel->remove($columns[$i]['id']);
+        }
+
+        $roles = array('draft', 'study', 'hairy', 'hard', 'medium', 'easy', 'done');
+        foreach ($roles as $k => $role) {
+            $this->projectMetadataModel->save($project['id'], array('qualkard_col_'.$role => $ids[$k]));
+        }
+
+        $helper->resetAll($project['id']);
+        $this->projectMetadataModel->save($project['id'], array('qualkard_enabled' => 1));
+
+        $this->flash->success(t('QualKard study board is ready.'));
+        $this->redirectToIntegrations($project);
+    }
+
+    /**
+     * Reset every card on the board: unread, moved to Drafts, armed-inert. Keeps the columns.
+     */
+    public function reset()
+    {
+        $project = $this->authorize();
+        (new QualKardHelper($this->container))->resetAll($project['id']);
+        $this->flash->success(t('All cards reset.'));
+        $this->redirectToIntegrations($project);
+    }
+
+    /**
+     * Disable QualKard on this board (non-destructive: leaves columns and cards as they are).
+     */
+    public function disable()
+    {
+        $project = $this->authorize();
+        $this->projectMetadataModel->save($project['id'], array('qualkard_enabled' => 0));
+        $this->flash->success(t('QualKard disabled on this board.'));
+        $this->redirectToIntegrations($project);
+    }
+
+    // Project-manager gate + CSRF, shared by every action.
+    private function authorize()
+    {
+        $project = $this->getProject();
+
+        if (! $this->helper->user->hasProjectAccess('ProjectEditController', 'edit', $project['id'])) {
+            throw new AccessForbiddenException();
+        }
+
+        $this->checkCSRFForm();
+
+        return $project;
+    }
+
+    private function redirectToIntegrations(array $project)
+    {
+        $this->response->redirect($this->helper->url->to('ProjectViewController', 'integrations', array('project_id' => $project['id'])));
+    }
+}

Helper/QualKardHelper.php

@@ -0,0 +1,222 @@
+<?php
+
+namespace Kanboard\Plugin\QualKard\Helper;
+
+use Kanboard\Core\Base;
+use Kanboard\Model\TaskModel;
+
+/**
+ * QualKard helper: the qualcard grading math (ported from Ruben's C program) plus the per-board gates.
+ *
+ * Scores per grade column: hairy=0.0, hard=1.3, medium=3.0, easy=5.0. The running average is
+ * M1 = (M0 + N)/2, with a new (unread) card seeded at N - 23%. The average maps to a review interval
+ * (qualcard grades G..A, 1..11 days). qualcard's H/same-day and the overdue decay are intentionally
+ * NOT ported: there is no "again now", and the Study column is itself the overdue backlog.
+ */
+class QualKardHelper extends Base
+{
+    const SCORE = array('hairy' => 0.0, 'hard' => 1.3, 'medium' => 3.0, 'easy' => 5.0);
+
+    /**
+     * Running average. New card (unread, $old === null) seeds at N - 23%; otherwise the qualcard mean.
+     */
+    public static function nextAverage($old, $score)
+    {
+        return $old === null ? ($score - 0.23 * $score) : (($old + $score) / 2.0);
+    }
+
+    /**
+     * Average -> review interval in days (qualcard grades G..A).
+     */
+    public static function intervalDays($avg)
+    {
+        if ($avg <= 0.60) {
+            return 1; // G
+        }
+        if ($avg <= 1.35) {
+            return 2; // F
+        }
+        if ($avg <= 2.20) {
+            return 3; // E
+        }
+        if ($avg <= 3.05) {
+            return 5; // D
+        }
+        if ($avg <= 3.90) {
+            return 7; // C
+        }
+        if ($avg <= 4.92) {
+            return 9; // B
+        }
+
+        return 11; // A
+    }
+
+    /**
+     * Next due timestamp: midnight, intervalDays() out.
+     */
+    public static function dueFrom($avg, $now = null)
+    {
+        $now = $now ?: time();
+
+        return strtotime('+'.self::intervalDays($avg).' days', strtotime('today', $now));
+    }
+
+    /**
+     * Mastery badge for a card's average: label + CSS class. null (unread) = "new" (yellow); otherwise
+     * a percent of 5, coloured red (<50) / green (<90) / blue (>=90).
+     *
+     * @param  float|null $avg
+     * @return array{label:string,class:string}
+     */
+    public static function badge($avg)
+    {
+        if ($avg === null) {
+            return array('label' => t('new'), 'class' => 'qk-new');
+        }
+
+        $pct = (int) round($avg / 5.0 * 100);
+        $class = $pct < 50 ? 'qk-low' : ($pct < 90 ? 'qk-mid' : 'qk-high');
+
+        return array('label' => $pct.'%', 'class' => $class);
+    }
+
+    /**
+     * Is QualKard enabled for this board?
+     *
+     * @param  int $project_id
+     * @return bool
+     */
+    public function isEnabled($project_id)
+    {
+        return (int) $this->projectMetadataModel->get($project_id, 'qualkard_enabled', 0) === 1;
+    }
+
+    /**
+     * Is the RecoReco plugin installed? (QualKard needs its move engine.)
+     *
+     * @return bool
+     */
+    public function hasRecoReco()
+    {
+        foreach ($this->container['pluginLoader']->getPlugins() as $plugin) {
+            if ($plugin->getPluginName() === 'RecoReco') {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * The column id stored for a board role ('draft', 'study', 'hairy', ... , 'done').
+     *
+     * @param  int    $project_id
+     * @param  string $role
+     * @return int
+     */
+    public function col($project_id, $role)
+    {
+        return (int) $this->projectMetadataModel->get($project_id, 'qualkard_col_'.$role, 0);
+    }
+
+    /**
+     * Is FinanceBuddy enabled on this board? QualKard refuses to convert a FinanceBuddy board (its
+     * restructure would wreck the finance columns).
+     *
+     * @param  int $project_id
+     * @return bool
+     */
+    public function fbEnabled($project_id)
+    {
+        return (int) $this->projectMetadataModel->get($project_id, 'financebuddy_enabled', 0) === 1;
+    }
+
+    /**
+     * Write the inert RecoReco config for a card: move-mode to Study, fire from anywhere but Done,
+     * daily (innocuous -- QualKard sets the due date on each grade), anchor 0 so RecoReco skips it
+     * until the first grade arms it. QualKard never toggles recoreco_enabled again.
+     *
+     * @param int $task_id
+     * @param int $project_id
+     */
+    public function arm($task_id, $project_id)
+    {
+        $this->taskMetadataModel->save($task_id, array(
+            'recoreco_enabled' => 1,
+            'recoreco_move' => 1,
+            'recoreco_target_column' => $this->col($project_id, 'study'),
+            'recoreco_trigger_column' => $this->col($project_id, 'done'),
+            'recoreco_trigger_invert' => 1,
+            'recoreco_frequency' => 'daily',
+            'recoreco_anchor' => 0,
+        ));
+    }
+
+    /**
+     * Reset one card: move to Drafts, mark unread, arm inert, clear the due date.
+     *
+     * @param int $task_id
+     * @param int $project_id
+     */
+    public function resetCard($task_id, $project_id)
+    {
+        $task = $this->taskFinderModel->getById($task_id);
+
+        if (empty($task)) {
+            return;
+        }
+
+        $this->taskPositionModel->movePosition($project_id, $task_id, $this->col($project_id, 'draft'), 1, (int) $task['swimlane_id'], false);
+        $this->taskMetadataModel->save($task_id, array('qualkard_avg' => '')); // '' = unread
+        $this->arm($task_id, $project_id);
+        $this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => 0));
+    }
+
+    /**
+     * Reset every card on a board.
+     *
+     * @param int $project_id
+     */
+    public function resetAll($project_id)
+    {
+        foreach ($this->taskFinderModel->getAll($project_id) as $task) {
+            $this->resetCard($task['id'], $project_id);
+        }
+    }
+
+    /**
+     * Grade a card by a score (a grade column's value): update the running average, compute the next
+     * due date, and arm the anchor. RecoReco moves the card from here.
+     *
+     * @param int   $task_id
+     * @param float $score
+     */
+    public function grade($task_id, $score)
+    {
+        $raw = $this->taskMetadataModel->get($task_id, 'qualkard_avg', '');
+        $old = ($raw === '' || $raw === null) ? null : (float) $raw;
+        $avg = self::nextAverage($old, $score);
+        $due = self::dueFrom($avg);
+
+        $this->taskMetadataModel->save($task_id, array(
+            'qualkard_avg' => (string) $avg,
+            'recoreco_anchor' => $due,
+        ));
+        $this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => $due));
+    }
+
+    /**
+     * The mastery badge (label + CSS class) for a card, from its stored average.
+     *
+     * @param  int $task_id
+     * @return array
+     */
+    public function cardBadge($task_id)
+    {
+        $raw = $this->taskMetadataModel->get($task_id, 'qualkard_avg', '');
+        $avg = ($raw === '' || $raw === null) ? null : (float) $raw;
+
+        return self::badge($avg);
+    }
+}

Plugin.php

@@ -1,35 +1,77 @@
 <?php
 
-namespace Kanboard\Plugin\Skeleton;
+namespace Kanboard\Plugin\QualKard;
 
 use Kanboard\Core\Plugin\Base;
+use Kanboard\Model\TaskModel;
 
+/**
+ * QualKard -- flashcard spaced repetition on Kanboard cards.
+ *
+ * Each card is a flashcard (title = prompt, description = answer). You grade a due card by dragging
+ * it into a grade column (Hairy/Hard/Medium/Easy); QualKard turns the grade into a due date via the
+ * qualcard average + interval, and the companion RecoReco plugin does all the card movement.
+ *
+ * Requires RecoReco (the move engine). Grading math is ported from Ruben's C program "qualcard".
+ */
 class Plugin extends Base
 {
     public function initialize()
     {
-        // 1. Render a visible word at the top of every page (the demo output).
-        $this->template->hook->attach('template:layout:top', 'skeleton:layout/header');
+        $container = $this->container;
 
-        // 2. Load the plugin stylesheet (currently empty -- proves the CSS hook fires).
+        // Per-board setup/reset/disable on Settings -> Integrations.
+        $this->template->hook->attach('template:project:integrations', 'qualKard:project/integration');
+
+        // New card on a QualKard board -> reset it (unread, armed inert, moved to Drafts).
+        $this->hook->on('model:task:creation:aftersave', function ($task_id) use ($container) {
+            $helper = new \Kanboard\Plugin\QualKard\Helper\QualKardHelper($container);
+            $task = $container['taskFinderModel']->getById($task_id);
+            if (! empty($task) && $helper->isEnabled($task['project_id'])) {
+                $helper->resetCard($task_id, (int) $task['project_id']);
+            }
+        });
+
+        // Card dragged INTO a grade column -> grade it (RecoReco then handles the movement). The
+        // plugin on() wrapper drops the event, so we subscribe on the dispatcher to get the TaskEvent.
+        $this->dispatcher->addListener(TaskModel::EVENT_MOVE_COLUMN, function ($event) use ($container) {
+            $task = $event['task'];
+            $helper = new \Kanboard\Plugin\QualKard\Helper\QualKardHelper($container);
+            if (! $helper->isEnabled($task['project_id'])) {
+                return;
+            }
+            $dst = (int) $event['dst_column_id'];
+            foreach (array('hairy', 'hard', 'medium', 'easy') as $role) {
+                if ($dst === $helper->col($task['project_id'], $role)) {
+                    $helper->grade($task['id'], \Kanboard\Plugin\QualKard\Helper\QualKardHelper::SCORE[$role]);
+                    return;
+                }
+            }
+        });
+
+        // Mastery badge under the card title on the board, plus its stylesheet.
+        $this->template->hook->attach('template:board:private:task:after-title', 'qualKard:board/badge');
+        $this->template->hook->attach('template:board:public:task:after-title', 'qualKard:board/badge');
         $this->hook->on('template:layout:css', array(
-            'template' => 'plugins/Skeleton/Asset/css/skeleton.css',
+            'template' => 'plugins/QualKard/Asset/css/qualkard.css',
         ));
+    }
 
-        // 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 getHelpers()
+    {
+        return array(
+            'Plugin\QualKard\Helper' => array('QualKardHelper'),
+        );
     }
 
     public function getPluginName()
     {
-        return 'Skeleton';
+        return 'QualKard';
     }
 
     public function getPluginDescription()
     {
-        return t('Reusable skeleton/template for building Kanboard plugins.');
+        return t('Flashcard spaced repetition: grade a card by dragging it to a column, and it comes back when due (needs RecoReco).');
     }
 
     public function getPluginAuthor()
@@ -39,12 +81,12 @@ class Plugin extends Base
 
     public function getPluginVersion()
     {
-        return '0.1.0';
+        return '0.6.0';
     }
 
     public function getPluginHomepage()
     {
-        return 'https://code.beco.cc/beco/kanboard-plugin-skeleton';
+        return 'https://code.beco.cc/beco/QualKard';
     }
 
     public function getCompatibleVersion()

Template/board/badge.php

@@ -0,0 +1,12 @@
+<?php
+// Mastery badge under the card title on a QualKard board. Server-rendered (survives board refresh).
+// Yellow "new" for an unread card; otherwise a percent of 5, red (<50) / green (<90) / blue (>=90).
+if (empty($task['project_id']) || ! $this->QualKardHelper->isEnabled($task['project_id'])) {
+    return;
+}
+
+$b = $this->QualKardHelper->cardBadge($task['id']);
+?>
+<div class="qk-line">
+    <span class="qk-badge <?= $b['class'] ?>"><?= $this->text->e($b['label']) ?></span>
+</div>

Template/layout/header.php

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

Template/project/integration.php

@@ -0,0 +1,37 @@
+<?php
+// QualKard is inside the shared Integrations form, so the buttons use formaction (NOT nested <form>s)
+// to post to QualKard's own controller. Set up is destructive; disabling only stops the automation.
+$has = $this->QualKardHelper->hasRecoReco();
+$fb = $this->QualKardHelper->fbEnabled($project['id']);
+$enabled = $this->QualKardHelper->isEnabled($project['id']);
+$blocked = ! $has || $fb;
+?>
+<h3><i class="fa fa-graduation-cap fa-fw" aria-hidden="true"></i> <?= t('QualKard') ?></h3>
+<div class="listing">
+<?php if ($enabled): ?>
+
+    <p class="form-help"><?= t('QualKard is enabled on this board.') ?></p>
+    <div class="form-actions">
+        <button type="submit" class="btn" formaction="<?= $this->url->href('QualKardController', 'reset', array('plugin' => 'QualKard', 'project_id' => $project['id'])) ?>" onclick="return confirm('<?= t('Reset every card to unread and move them to Drafts. Continue?') ?>');"><?= t('Reset all cards') ?></button>
+        <button type="submit" class="btn btn-red" formaction="<?= $this->url->href('QualKardController', 'disable', array('plugin' => 'QualKard', 'project_id' => $project['id'])) ?>"><?= t('Disable QualKard machinery') ?></button>
+    </div>
+    <p class="form-help"><?= t('"Disable" only stops the QualKard automation -- it does not restructure the board or touch your cards.') ?></p>
+
+<?php else: ?>
+
+    <p class="form-help">
+    <?php if (! $has): ?>
+        <?= t('QualKard needs the RecoReco plugin (its move engine).') ?>
+    <?php elseif ($fb): ?>
+        <?= t('Disabled while FinanceBuddy is enabled here -- QualKard would restructure the columns.') ?>
+    <?php else: ?>
+        <?= t('Set up turns this project into a study board: columns become Drafts | Study | Hairy | Hard | Medium | Easy | Done and every card moves to Drafts.') ?>
+    <?php endif ?>
+    </p>
+    <div class="form-actions"<?= $blocked ? ' style="opacity:0.5"' : '' ?>>
+        <button type="submit" class="btn btn-blue" <?= $blocked ? 'disabled="disabled"' : '' ?> formaction="<?= $this->url->href('QualKardController', 'setup', array('plugin' => 'QualKard', 'project_id' => $project['id'])) ?>" onclick="return confirm('<?= t('This restructures the board and moves all cards to Drafts. Continue?') ?>');"><?= t('Set up QualKard study board') ?></button>
+    </div>
+
+<?php endif ?>
+</div>
+<hr>

VERSION

@@ -1 +1 @@
-QualKard v0.1
+QualKard v0.6