@linxin666/dsh-client-ui-task-board 0.1.14 → 0.1.15

package/src/core/controller.ts

@@ -7,14 +7,22 @@
  * navigates to a session (the sessions-list `current` selection changes).
  * Framework-free (structural runtime faces) so the whole orchestration is
  * unit-testable with fakes.
+ *
+ * The per use-case domain transitions (create/update/delete/schedule) live in
+ * dedicated modules under core/use-cases and are applied here; the controller
+ * owns only the orchestration seam (state, persistence, notify, execution,
+ * navigation, reconciliation).
  */
 import { ExecutionService, type ExecutionEvent } from './execution.ts'
-import { isValidCron, nextRunAtMs } from './schedule.ts'
 import type { TaskStore } from './store.ts'
 import {
-  createTask, settleExecution, startExecution, withSchedule, withStatus,
+  settleExecution, startExecution, withStatus,
   type NewTaskInput, type TaskRecord, type TaskStatus,
 } from './tasks.ts'
+import { applyCreateTask } from './use-cases/task-create.ts'
+import { applyDeleteTask } from './use-cases/task-delete.ts'
+import { applyScheduleNextRun as applyScheduleRollForward, applySetSchedule } from './use-cases/task-schedule.ts'
+import { applyUpdateTask } from './use-cases/task-update.ts'
 
 /** The sessions face the controller needs for navigation awareness. */
 export interface SessionsControllerFace {
@@ -168,21 +176,18 @@ export class BoardController {
     this.notify()
   }
 
-  // --- task mutations ---------------------------------------------------------
+  // --- task mutations (use-case transitions in core/use-cases) -----------------
 
   createTask(input: NewTaskInput): TaskRecord | undefined {
-    const title = input.title.trim()
-    if (title === '') return undefined
-    const task = createTask(input, this.now(), this.uuid())
-    this.tasks = [...this.tasks, task]
+    const { task, tasks } = applyCreateTask(this.tasks, input, this.now(), this.uuid())
+    if (task === undefined) return undefined
+    this.tasks = [...tasks]
     this.persistAndNotify()
     return task
   }
 
   updateTask(id: string, patch: Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt'>>): void {
-    this.tasks = this.tasks.map(task => task.id === id
-      ? { ...task, ...patch, updatedAt: this.now() }
-      : task)
+    this.tasks = [...applyUpdateTask(this.tasks, id, patch, this.now())]
     this.persistAndNotify()
   }
 
@@ -192,8 +197,9 @@ export class BoardController {
   }
 
   deleteTask(id: string): void {
-    this.tasks = this.tasks.filter(task => task.id !== id)
-    if (this.selectedTaskId === id) this.selectedTaskId = undefined
+    const { tasks, selectionCleared } = applyDeleteTask(this.tasks, this.selectedTaskId, id)
+    this.tasks = [...tasks]
+    if (selectionCleared) this.selectedTaskId = undefined
     this.persistAndNotify()
   }
 
@@ -203,21 +209,15 @@ export class BoardController {
    * Update a task's schedule rule. A blank or invalid cron expression is
    * rejected (returns false, state untouched). When the rule ends up enabled
    * the next run instant is computed immediately; a disabled rule carries no
-   * next-run instant.
+   * next-run instant. Delegates the domain transition to the schedule use case.
    * @param id - the task to schedule.
    * @param patch - fields to change (absent fields keep their current value).
    * @returns true when applied, false when rejected (invalid cron / unknown task).
    */
   setSchedule(id: string, patch: { enabled?: boolean; cron?: string }): boolean {
-    const task = this.tasks.find(candidate => candidate.id === id)
-    if (task === undefined) return false
-    const current = task.schedule
-    const cron = (patch.cron ?? current?.cron ?? '').trim()
-    if (cron === '' || !isValidCron(cron)) return false
-    const enabled = patch.enabled ?? current?.enabled ?? false
-    const nextRunAt = enabled ? nextRunAtMs(cron, this.now()) : undefined
-    this.tasks = this.tasks.map(candidate =>
-      candidate.id === id ? withSchedule(candidate, { enabled, cron, nextRunAt }, this.now()) : candidate)
+    const { tasks, applied } = applySetSchedule(this.tasks, id, patch, this.now())
+    if (!applied) return false
+    this.tasks = [...tasks]
     this.persistAndNotify()
     return true
   }
@@ -228,10 +228,8 @@ export class BoardController {
    * schedule rule (it was deleted mid-tick, for example).
    */
   applyScheduleNextRun(id: string, nextRunAt: number | undefined, lastTriggeredAt: number | undefined): void {
-    this.tasks = this.tasks.map(task =>
-      task.id === id && task.schedule !== undefined
-        ? withSchedule(task, { nextRunAt, lastTriggeredAt }, this.now())
-        : task)
+    const next = applyScheduleRollForward(this.tasks, id, nextRunAt, lastTriggeredAt, this.now())
+    this.tasks = [...next]
     this.persistAndNotify()
   }
 
@@ -392,3 +390,4 @@ function attachSessionId(
       execution.id === executionId ? { ...execution, sessionId } : execution),
   }
 }
+

package/src/core/scheduler.ts

@@ -9,6 +9,12 @@
  * a task still running at its due instant is skipped by the controller's
  * runTask guard and simply waits for the next cron match.
  *
+ * The ticker is controlled: `start` arms a single interval guarded by an
+ * idempotence check (a second start while running is a no-op, so wiring can
+ * never leak a duplicate timer), and `stop`/`dispose` clear the timer and
+ * drop the environment listeners. The board unmount path calls stop/dispose,
+ * so no interval or listener outlives the board.
+ *
  * Framework-free: all runtime access flows through the injected deps
  * (structural faces), so tests drive ticks directly without timers.
  */
@@ -47,27 +53,54 @@ export interface SchedulerDeps {
  */
 export class SchedulerService {
   private timer: ReturnType<typeof setInterval> | undefined
+  private environmentListener: (() => void) | undefined
   private disposed = false
+  private started = false
 
   /** @param deps - tasks/clock/trigger/apply faces (see {@link SchedulerDeps}). */
   constructor(private readonly deps: SchedulerDeps) {}
 
-  /** Start ticking: one immediate check (catch-up after reload) + the interval. */
+  /**
+   * Start ticking: one immediate check (catch-up after reload) + the interval.
+   * Single-instance: a second start while already armed is a no-op, so a
+   * re-entrant mount can never stack a duplicate timer.
+   */
   start(): void {
     if (this.disposed) return
+    if (this.started) return
+    this.started = true
     // Immediate catch-up tick: schedules whose due instant passed while the
     // tab was closed are triggered as soon as the runtime is ready.
     this.tick()
     this.timer = setInterval(() => { this.tick() }, this.deps.tickMs ?? 60_000)
-    this.deps.environment?.addEventListener('visibilitychange', this.onVisibility)
+    if (this.deps.environment !== undefined) {
+      this.environmentListener = () => { this.tick() }
+      this.deps.environment.addEventListener('visibilitychange', this.environmentListener)
+    }
+  }
+
+  /**
+   * Stop ticking and drop listeners (idempotent). Preferred shutdown verb for
+   * callers that treat the scheduler as a controlled ticker; `dispose` is an
+   * alias.
+   */
+  stop(): void {
+    this.dispose()
   }
 
   /** Stop ticking and drop listeners (idempotent). */
   dispose(): void {
+    if (this.disposed && this.timer === undefined && this.environmentListener === undefined) return
     this.disposed = true
-    if (this.timer !== undefined) clearInterval(this.timer)
-    this.timer = undefined
-    this.deps.environment?.removeEventListener('visibilitychange', this.onVisibility)
+    this.started = false
+    if (this.timer !== undefined) {
+      clearInterval(this.timer)
+      this.timer = undefined
+    }
+    if (this.environmentListener !== undefined && this.deps.environment !== undefined) {
+      this.deps.environment.removeEventListener('visibilitychange', this.environmentListener)
+      this.environmentListener = undefined
+    }
   }
 
   /**
@@ -99,6 +132,5 @@ export class SchedulerService {
       if (accepted) this.deps.applySchedule(task.id, next, now)
     }
   }
-
-  private readonly onVisibility = (): void => { this.tick() }
 }
+

package/src/core/use-cases/task-create.ts

@@ -0,0 +1,33 @@
+/**
+ * Create-task use case: mint a new task from user input, rejecting a blank
+ * title. Pure ledger transition (no persistence or notify — the controller
+ * orchestrates those), so it is unit-testable without any runtime face.
+ */
+import { createTask, type NewTaskInput, type TaskRecord } from '../tasks.ts'
+
+/** Result of a create transition: the new task (when accepted) + the next ledger. */
+export interface CreateTaskResult {
+  /** The minted task, or undefined when the input was rejected (blank title). */
+  task: TaskRecord | undefined
+  /** The next ledger; identical reference when rejected. */
+  tasks: readonly TaskRecord[]
+}
+
+/**
+ * Apply a create against the current ledger. Returns the new task and the
+ * appended ledger, or the unchanged ledger when the title is blank.
+ * @param tasks - current ledger.
+ * @param input - raw user input (title/description/prompt).
+ * @param now - clock instant (ms epoch).
+ * @param id - minted task id.
+ */
+export function applyCreateTask(
+  tasks: readonly TaskRecord[],
+  input: NewTaskInput,
+  now: number,
+  id: string,
+): CreateTaskResult {
+  if (input.title.trim() === '') return { task: undefined, tasks }
+  const task = createTask(input, now, id)
+  return { task, tasks: [...tasks, task] }
+}

package/src/core/use-cases/task-delete.ts

@@ -0,0 +1,33 @@
+/**
+ * Delete-task use case: drop a task from the ledger and clear the selection
+ * when it pointed at the removed task. Pure ledger transition (no persistence
+ * or notify — the controller orchestrates those).
+ */
+import type { TaskRecord } from '../tasks.ts'
+
+/** Result of a delete transition. */
+export interface DeleteTaskResult {
+  /** The next ledger (the removed task absent). */
+  tasks: readonly TaskRecord[]
+  /** Whether the previous selection referenced the removed task. */
+  selectionCleared: boolean
+}
+
+/**
+ * Apply a delete across the ledger. The selection (a task id) is cleared when
+ * it matches the removed task, so the UI never lingers on a vanished detail.
+ * @param tasks - current ledger.
+ * @param selectedTaskId - the currently selected task id (may be undefined).
+ * @param id - the task to remove.
+ */
+export function applyDeleteTask(
+  tasks: readonly TaskRecord[],
+  selectedTaskId: string | undefined,
+  id: string,
+): DeleteTaskResult {
+  const next = tasks.filter(task => task.id !== id)
+  return {
+    tasks: next,
+    selectionCleared: selectedTaskId === id,
+  }
+}

package/src/core/use-cases/task-schedule.ts

@@ -0,0 +1,74 @@
+/**
+ * Schedule use case: arm/disarm a task's cron rule and roll a rule forward.
+ * Pure ledger transitions (no persistence or notify — the controller
+ * orchestrates those). Validation and next-run computation live here, sharing
+ * the core cron parser (schedule.ts) and the withSchedule transition.
+ */
+import { isValidCron, nextRunAtMs } from '../schedule.ts'
+import { withSchedule, type TaskRecord } from '../tasks.ts'
+
+/** Fields the schedule use case may change on a rule. */
+export interface SetSchedulePatch {
+  enabled?: boolean
+  cron?: string
+}
+
+/** Result of arming/disarming a rule. */
+export interface SetScheduleResult {
+  /** The next ledger; unchanged reference when rejected. */
+  tasks: readonly TaskRecord[]
+  /** Whether the rule was applied (false on unknown task / invalid cron). */
+  applied: boolean
+}
+
+/**
+ * Set a task's schedule rule. A blank or invalid cron is rejected (state
+ * untouched); an enabled rule computes the next run instant immediately, a
+ * disabled or invalid one carries no next-run instant.
+ * @param tasks - current ledger.
+ * @param id - the task to schedule.
+ * @param patch - rule fields to change (absent fields keep their current value).
+ * @param now - clock instant (ms epoch).
+ */
+export function applySetSchedule(
+  tasks: readonly TaskRecord[],
+  id: string,
+  patch: SetSchedulePatch,
+  now: number,
+): SetScheduleResult {
+  const task = tasks.find(candidate => candidate.id === id)
+  if (task === undefined) return { tasks, applied: false }
+  const current = task.schedule
+  const cron = (patch.cron ?? current?.cron ?? '').trim()
+  if (cron === '' || !isValidCron(cron)) return { tasks, applied: false }
+  const enabled = patch.enabled ?? current?.enabled ?? false
+  const nextRunAt = enabled ? nextRunAtMs(cron, now) : undefined
+  return {
+    tasks: tasks.map(candidate =>
+      candidate.id === id ? withSchedule(candidate, { enabled, cron, nextRunAt }, now) : candidate),
+    applied: true,
+  }
+}
+
+/**
+ * Roll a task's schedule rule forward (scheduler callback): persist the next
+ * due instant and the trigger instant. No-op for tasks without a rule (deleted
+ * mid-tick, for example).
+ * @param tasks - current ledger.
+ * @param id - the task to roll forward.
+ * @param nextRunAt - next due instant (may be undefined to clear).
+ * @param lastTriggeredAt - the trigger instant of this run.
+ * @param now - clock instant (ms epoch).
+ */
+export function applyScheduleNextRun(
+  tasks: readonly TaskRecord[],
+  id: string,
+  nextRunAt: number | undefined,
+  lastTriggeredAt: number | undefined,
+  now: number,
+): readonly TaskRecord[] {
+  return tasks.map(task =>
+    task.id === id && task.schedule !== undefined
+      ? withSchedule(task, { nextRunAt, lastTriggeredAt }, now)
+      : task)
+}

package/src/core/use-cases/task-update.ts

@@ -0,0 +1,26 @@
+/**
+ * Update-task use case: apply an editable-field patch (title/description/
+ * prompt) with a fresh updatedAt. Pure ledger transition (no persistence or
+ * notify — the controller orchestrates those).
+ */
+import type { TaskRecord } from '../tasks.ts'
+
+/** Editable fields on a task (the update patch surface). */
+export type TaskUpdatePatch = Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt'>>
+
+/**
+ * Apply an update across the ledger. Tasks that do not match the id are left
+ * untouched; the matched task receives the patch plus a fresh updatedAt.
+ * @param tasks - current ledger.
+ * @param id - the task to update.
+ * @param patch - editable-field changes.
+ * @param now - clock instant (ms epoch).
+ */
+export function applyUpdateTask(
+  tasks: readonly TaskRecord[],
+  id: string,
+  patch: TaskUpdatePatch,
+  now: number,
+): readonly TaskRecord[] {
+  return tasks.map(task => task.id === id ? { ...task, ...patch, updatedAt: now } : task)
+}