trekoon 0.3.1 → 0.3.2

package/src/board/assets/runtime/delegation.js

@@ -1,3 +1,5 @@
+import { isValidTransition } from "../state/utils.js";
+
 /**
  * Event delegation system for the board runtime.
  *
@@ -89,6 +91,31 @@ export function createDelegation(rootElement, actions) {
       return;
     }
 
+    // -- Status filter pills ---------------------------------------------------
+    const epicFilterEl = target.closest("[data-toggle-epic-status-filter]");
+    if (epicFilterEl) {
+      actions.toggleEpicStatusFilter(epicFilterEl.dataset.toggleEpicStatusFilter);
+      return;
+    }
+
+    const taskFilterEl = target.closest("[data-toggle-task-status-filter]");
+    if (taskFilterEl) {
+      actions.toggleTaskStatusFilter(taskFilterEl.dataset.toggleTaskStatusFilter);
+      return;
+    }
+
+    const resetEpicFilterEl = target.closest("[data-reset-epic-filter]");
+    if (resetEpicFilterEl) {
+      actions.resetEpicFilter();
+      return;
+    }
+
+    const resetTaskFilterEl = target.closest("[data-reset-task-filter]");
+    if (resetTaskFilterEl) {
+      actions.resetTaskFilter();
+      return;
+    }
+
     // -- Navigation -----------------------------------------------------------
 
     const navEl = target.closest("[data-nav]");
@@ -276,6 +303,15 @@ export function createDelegation(rootElement, actions) {
   // ---------------------------------------------------------------------------
   // Drag-and-drop delegation
   // ---------------------------------------------------------------------------
+  let draggedTaskStatus = null;
+
+  function cleanupDragFeedback() {
+    draggedTaskStatus = null;
+    for (const el of rootElement.querySelectorAll(".board-drop-valid, .board-drop-invalid")) {
+      el.classList.remove("board-drop-valid", "board-drop-invalid");
+    }
+  }
+
   function handleDragstart(event) {
     const draggable = event.target.closest("[data-draggable-task]");
     if (!draggable) return;
@@ -290,11 +326,28 @@ export function createDelegation(rootElement, actions) {
 
     event.dataTransfer?.setData("text/task-id", taskId);
     event.dataTransfer?.setData("text/plain", taskId);
+    draggedTaskStatus = actions.getTaskStatus(taskId);
   }
 
   function handleDragover(event) {
-    if (event.target.closest("[data-drop-status]")) {
+    const column = event.target.closest("[data-drop-status]");
+    if (!column) return;
+
+    const targetStatus = column.dataset.dropStatus;
+    if (draggedTaskStatus && isValidTransition(draggedTaskStatus, targetStatus)) {
       event.preventDefault();
+      column.classList.add("board-drop-valid");
+      column.classList.remove("board-drop-invalid");
+    } else if (draggedTaskStatus && targetStatus !== draggedTaskStatus) {
+      column.classList.add("board-drop-invalid");
+      column.classList.remove("board-drop-valid");
+    }
+  }
+
+  function handleDragleave(event) {
+    const column = event.target.closest("[data-drop-status]");
+    if (column && !column.contains(event.relatedTarget)) {
+      column.classList.remove("board-drop-valid", "board-drop-invalid");
     }
   }
 
@@ -309,7 +362,18 @@ export function createDelegation(rootElement, actions) {
       event.dataTransfer?.getData("text/task-id") ||
       event.dataTransfer?.getData("text/plain");
     const nextStatus = column.dataset.dropStatus;
+
+    if (draggedTaskStatus && !isValidTransition(draggedTaskStatus, nextStatus)) {
+      cleanupDragFeedback();
+      return;
+    }
+
     actions.dropTaskStatus(taskId, nextStatus);
+    cleanupDragFeedback();
+  }
+
+  function handleDragend() {
+    cleanupDragFeedback();
   }
 
   // ---------------------------------------------------------------------------
@@ -321,7 +385,9 @@ export function createDelegation(rootElement, actions) {
   rootElement.addEventListener("submit", handleSubmit);
   rootElement.addEventListener("dragstart", handleDragstart);
   rootElement.addEventListener("dragover", handleDragover);
+  rootElement.addEventListener("dragleave", handleDragleave);
   rootElement.addEventListener("drop", handleDrop);
+  rootElement.addEventListener("dragend", handleDragend);
   rootElement.addEventListener("keydown", handleDelegatedKeydown);
   window.addEventListener("keydown", handleKeydown);
 
@@ -335,7 +401,9 @@ export function createDelegation(rootElement, actions) {
     rootElement.removeEventListener("submit", handleSubmit);
     rootElement.removeEventListener("dragstart", handleDragstart);
     rootElement.removeEventListener("dragover", handleDragover);
+    rootElement.removeEventListener("dragleave", handleDragleave);
     rootElement.removeEventListener("drop", handleDrop);
+    rootElement.removeEventListener("dragend", handleDragend);
     rootElement.removeEventListener("keydown", handleDelegatedKeydown);
     window.removeEventListener("keydown", handleKeydown);
   };

package/src/board/assets/state/actions.js

@@ -1,5 +1,5 @@
 import { copyTextToClipboard } from "../runtime/clipboard.js";
-import { orderEpicsNewestFirst } from "./store.js";
+import { DEFAULT_STATUS_FILTER, orderEpicsNewestFirst } from "./store.js";
 
 function cloneSnapshot(snapshot) {
   if (typeof structuredClone === "function") {
@@ -404,6 +404,10 @@ export function createBoardActions(options) {
     removeDependency(sourceId, dependsOnId) {
       api.removeDependency(sourceId, dependsOnId, (snapshot) => removeDependencyInSnapshot(snapshot, sourceId, dependsOnId, normalizeSnapshot));
     },
+    getTaskStatus(taskId) {
+      const task = getTaskById(taskId);
+      return task?.status ?? null;
+    },
     dropTaskStatus(taskId, nextStatus) {
       const task = getTaskById(taskId);
       if (!task || !nextStatus || task.status === nextStatus) {
@@ -426,6 +430,28 @@ export function createBoardActions(options) {
         cascadeEpicStatusInSnapshot(snapshot, epicId, normalizedStatus, normalizeSnapshot),
       );
     },
+    toggleEpicStatusFilter(status) {
+      const current = store.epicStatusFilter || { ...DEFAULT_STATUS_FILTER };
+      store.epicStatusFilter = { ...current, [status]: !current[status] };
+      persist();
+      rerender();
+    },
+    toggleTaskStatusFilter(status) {
+      const current = store.taskStatusFilter || { ...DEFAULT_STATUS_FILTER };
+      store.taskStatusFilter = { ...current, [status]: !current[status] };
+      persist();
+      rerender();
+    },
+    resetEpicFilter() {
+      store.epicStatusFilter = { ...DEFAULT_STATUS_FILTER };
+      persist();
+      rerender();
+    },
+    resetTaskFilter() {
+      store.taskStatusFilter = { ...DEFAULT_STATUS_FILTER };
+      persist();
+      rerender();
+    },
     handleKeydown(event) {
       const boardState = getBoardState();
       const activeElement = document.activeElement;

package/src/board/assets/state/store.js

@@ -9,6 +9,18 @@ function normalizeSearch(value) {
 
 // --- Persistence helpers ---
 
+export const DEFAULT_STATUS_FILTER = { todo: true, blocked: true, in_progress: true, done: false };
+
+function readStatusFilter(raw) {
+  if (typeof raw !== "object" || raw === null) return { ...DEFAULT_STATUS_FILTER };
+  return {
+    todo: typeof raw.todo === "boolean" ? raw.todo : DEFAULT_STATUS_FILTER.todo,
+    blocked: typeof raw.blocked === "boolean" ? raw.blocked : DEFAULT_STATUS_FILTER.blocked,
+    in_progress: typeof raw.in_progress === "boolean" ? raw.in_progress : DEFAULT_STATUS_FILTER.in_progress,
+    done: typeof raw.done === "boolean" ? raw.done : DEFAULT_STATUS_FILTER.done,
+  };
+}
+
 export function readStoredState() {
   try {
     return JSON.parse(localStorage.getItem(STATE_STORAGE_KEY) || "{}");
@@ -77,13 +89,25 @@ export function orderEpicsNewestFirst(epics) {
 
 // --- Derived state selectors ---
 
+/** Recently-done epics stay visible for 24h even when the "done" filter is off. */
+const DONE_GRACE_PERIOD_MS = 86400000;
+
 const selectVisibleEpics = createSelector(
-  (s) => [s.snapshot?.epics, s.searchQuery],
-  (epics, searchQuery) => {
+  (s) => [s.snapshot?.epics, s.searchQuery, s.epicStatusFilter],
+  (epics, searchQuery, epicStatusFilter) => {
     if (!epics) return [];
+    const now = Date.now();
+    const filtered = epics.filter((epic) => {
+      if (epic.status === "done") {
+        if (!epicStatusFilter.done && (now - epic.updatedAt) > DONE_GRACE_PERIOD_MS) return false;
+      } else if (!epicStatusFilter[epic.status]) {
+        return false;
+      }
+      return true;
+    });
     const matchingEpics = searchQuery.length === 0
-      ? epics
-      : epics.filter((epic) => epic.searchText.includes(searchQuery));
+      ? filtered
+      : filtered.filter((epic) => epic.searchText.includes(searchQuery));
 
     return orderEpicsNewestFirst(matchingEpics);
   },
@@ -100,11 +124,12 @@ const selectTasksInScope = createSelector(
 );
 
 const selectVisibleTasks = createSelector(
-  (s) => [selectTasksInScope(s), s.searchQuery],
-  (tasksInScope, searchQuery) => {
+  (s) => [selectTasksInScope(s), s.searchQuery, s.taskStatusFilter],
+  (tasksInScope, searchQuery, taskStatusFilter) => {
+    const filtered = tasksInScope.filter((task) => taskStatusFilter[task.status]);
     return searchQuery.length === 0
-      ? tasksInScope
-      : tasksInScope.filter((task) => task.searchText.includes(searchQuery));
+      ? filtered
+      : filtered.filter((task) => task.searchText.includes(searchQuery));
   },
 );
 
@@ -287,6 +312,8 @@ export function createStore(initialSnapshot, options = {}) {
     notice: null,
     isMutating: false,
     notesPanelOpen: storedState.notesPanelOpen === true,
+    epicStatusFilter: readStatusFilter(storedState.epicStatusFilter),
+    taskStatusFilter: readStatusFilter(storedState.taskStatusFilter),
   };
 
   /** @type {Set<(state: object) => void>} */
@@ -306,6 +333,8 @@ export function createStore(initialSnapshot, options = {}) {
         view: state.view,
         selectedTaskId: state.selectedTaskId,
         notesPanelOpen: state.notesPanelOpen,
+        epicStatusFilter: state.epicStatusFilter,
+        taskStatusFilter: state.taskStatusFilter,
       });
   }
 

package/src/board/assets/state/utils.js

@@ -220,3 +220,45 @@ export function escapeHtml(value) {
     .replaceAll(">", ">")
     .replaceAll('"', """);
 }
+
+/**
+ * Valid status transitions mirroring the backend state machine (src/domain/types.ts).
+ * @type {Map<string, Set<string>>}
+ */
+export const VALID_TRANSITIONS = new Map([
+  ["todo", new Set(["in_progress", "blocked"])],
+  ["in_progress", new Set(["done", "blocked"])],
+  ["blocked", new Set(["in_progress", "todo"])],
+  ["done", new Set(["in_progress"])],
+]);
+
+/**
+ * Get the list of statuses a node can transition to from its current status.
+ * @param {string} currentStatus
+ * @returns {string[]}
+ */
+export function getValidTargets(currentStatus) {
+  const targets = VALID_TRANSITIONS.get(currentStatus);
+  return targets ? Array.from(targets) : [];
+}
+
+/**
+ * Check whether transitioning from one status to another is valid.
+ * @param {string} from
+ * @param {string} to
+ * @returns {boolean}
+ */
+export function isValidTransition(from, to) {
+  const targets = VALID_TRANSITIONS.get(from);
+  return targets ? targets.has(to) : false;
+}
+
+/**
+ * Return the current status plus all valid targets, useful for populating
+ * status select dropdowns.
+ * @param {string} currentStatus
+ * @returns {string[]}
+ */
+export function getSelectableStatuses(currentStatus) {
+  return [currentStatus, ...getValidTargets(currentStatus)];
+}

package/src/board/assets/styles/board.css

@@ -1929,3 +1929,71 @@ textarea,
 .\!px-2 { padding-inline: 0.5rem !important; }
 .\!text-xs { font-size: 0.75rem !important; line-height: 1rem !important; }
 .\!min-h-0 { min-height: 0 !important; }
+
+/* --- Drag-and-drop transition feedback --- */
+.board-drop-valid {
+  outline: 2px solid var(--board-accent);
+  outline-offset: -2px;
+  background: rgba(var(--board-accent-rgb, 99, 102, 241), 0.06);
+}
+
+.board-drop-invalid {
+  outline: 2px dashed rgba(239, 68, 68, 0.4);
+  outline-offset: -2px;
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+/* --- Filter pills --- */
+.board-filter-bar {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.375rem;
+  margin-top: 0.75rem;
+}
+
+.board-filter-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.25rem 0.75rem;
+  border-radius: 9999px;
+  border: 1px solid var(--board-border);
+  background: var(--board-surface-2);
+  color: var(--board-text-muted);
+  font-size: 0.6875rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.14em;
+  cursor: pointer;
+  transition: opacity 0.2s, border-color 0.2s, background 0.2s;
+  user-select: none;
+}
+
+.board-filter-pill:hover {
+  border-color: var(--board-border-strong);
+  background: rgba(255, 255, 255, 0.08);
+}
+
+.board-filter-pill:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--board-border-strong);
+}
+
+.board-filter-pill--active {
+  opacity: 1;
+}
+
+.board-filter-pill--inactive {
+  opacity: 0.4;
+}
+
+.board-filter-pill--reset {
+  color: var(--board-accent);
+  border-color: var(--board-accent);
+}
+
+.board-filter-pill--reset:hover {
+  background: rgba(var(--board-accent-rgb, 99, 102, 241), 0.1);
+}

package/src/commands/skills.ts

@@ -1,4 +1,4 @@
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -79,6 +79,10 @@ function resolveBundledSkillFilePath(): string {
   return fileURLToPath(new URL("../../.agents/skills/trekoon/SKILL.md", import.meta.url));
 }
 
+function resolveBundledSkillDirPath(): string {
+  return fileURLToPath(new URL("../../.agents/skills/trekoon", import.meta.url));
+}
+
 function toAbsolutePath(cwd: string, pathValue: string): string {
   if (isAbsolute(pathValue)) {
     return pathValue;
@@ -234,6 +238,7 @@ function resolveEditorConfigDir(cwd: string, editor: EditorName): string {
 
 function installCanonicalSkill(cwd: string): CliResult | { sourcePath: string; installedPath: string; installedDir: string } {
   const sourcePath: string = resolveBundledSkillFilePath();
+  const sourceDir: string = resolveBundledSkillDirPath();
   if (!existsSync(sourcePath)) {
     return failResult({
       command: "skills.install",
@@ -255,6 +260,12 @@ function installCanonicalSkill(cwd: string): CliResult | { sourcePath: string; i
   try {
     mkdirSync(installedDir, { recursive: true });
     copyFileSync(sourcePath, installedPath);
+    // Copy reference guides if they exist in the bundled source.
+    const sourceRefDir: string = join(sourceDir, "reference");
+    if (existsSync(sourceRefDir)) {
+      const installedRefDir: string = join(installedDir, "reference");
+      cpSync(sourceRefDir, installedRefDir, { recursive: true });
+    }
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : "Unknown skills install failure";
     return failResult({
@@ -298,39 +309,28 @@ function replaceOrCreateSymlink(
 
   const existing = lstatSync(linkPath);
   if (!existing.isSymbolicLink()) {
-    return failResult({
-      command: "skills.install",
-      human: `Cannot create symlink: path exists and is not a link (${linkPath}).`,
-      data: {
-        code: "path_conflict",
-        linkPath,
-        targetPath,
-      },
-      error: {
-        code: "path_conflict",
-        message: "Symlink destination exists as a non-link path",
-      },
-    });
+    // Replace stale directory or file with symlink to the canonical location.
+    rmSync(linkPath, { recursive: true, force: true });
+    const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
+    if (boundaryFailure) {
+      return boundaryFailure;
+    }
+    symlinkSync(symlinkTarget, linkPath, "dir");
+    return null;
   }
 
   const existingRawTarget: string = readlinkSync(linkPath);
   const existingAbsoluteTarget: string = toAbsolutePath(dirname(linkPath), existingRawTarget);
   const expectedTarget: string = resolve(targetPath);
   if (existingAbsoluteTarget !== expectedTarget) {
-    return failResult({
-      command: "skills.install",
-      human: `Cannot replace existing link at ${linkPath}; it points to ${existingAbsoluteTarget}.`,
-      data: {
-        code: "path_conflict",
-        linkPath,
-        existingTarget: existingAbsoluteTarget,
-        expectedTarget,
-      },
-      error: {
-        code: "path_conflict",
-        message: "Symlink destination points to a different target",
-      },
-    });
+    // Replace symlink pointing to a different target.
+    rmSync(linkPath, { force: true });
+    const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
+    if (boundaryFailure) {
+      return boundaryFailure;
+    }
+    symlinkSync(symlinkTarget, linkPath, "dir");
+    return null;
   }
 
   rmSync(linkPath, { force: true });
@@ -525,12 +525,16 @@ function updateEditorLink(
 
   const entry = lstatSync(linkPath);
   if (!entry.isSymbolicLink()) {
+    // Replace stale directory or file with symlink to the canonical location.
+    rmSync(linkPath, { recursive: true, force: true });
+    mkdirSync(dirname(linkPath), { recursive: true });
+    symlinkSync(symlinkTarget, linkPath, "dir");
     return {
       editor,
       linkPath,
       expectedTarget,
-      action: "skipped_conflict",
-      conflictCode: "non_link",
+      action: "refreshed",
+      conflictCode: null,
       existingTarget: null,
     };
   }
@@ -539,12 +543,15 @@ function updateEditorLink(
   const existingTarget: string = toAbsolutePath(dirname(linkPath), existingRawTarget);
 
   if (existingTarget !== expectedTarget) {
+    // Replace symlink pointing to a different target.
+    rmSync(linkPath, { force: true });
+    symlinkSync(symlinkTarget, linkPath, "dir");
     return {
       editor,
       linkPath,
       expectedTarget,
-      action: "skipped_conflict",
-      conflictCode: "wrong_target",
+      action: "refreshed",
+      conflictCode: null,
       existingTarget,
     };
   }