dsh-taskboard 0.4.5 → 0.5.1

package/src/host/scheduler.ts

@@ -8,7 +8,7 @@
  *
  * @module dsh-taskboard/host/scheduler
  */
-import { nextCronTime, parseCron, type TaskLedger } from '../shared/protocol.ts'
+import { newCommentId, nextCronTime, normalizeBody, parseCron, type TaskLedger } from '../shared/protocol.ts'
 import { DEFAULT_MAX_CONCURRENT, type ExecutionService } from './execution.ts'
 import type { TaskStore } from './store.ts'
 
@@ -25,44 +25,61 @@ export interface SchedulerDeps {
   now: () => number
   /** Max concurrently running executions (default 3; must match the execution service). */
   maxConcurrent?: number
-  /** Timer face (injectable for tests). */
+  /** Timer face (injectable for tests). The timeout pair is optional so
+   *  older injections keep working; gaps fall back to the globals. */
   timers?: {
     setInterval(fn: () => void, ms: number): unknown
     clearInterval(handle: unknown): void
+    setTimeout?(fn: () => void, ms: number): unknown
+    clearTimeout?(handle: unknown): void
   }
 }
 
+type SchedulerTimers = NonNullable<SchedulerDeps['timers']>
+
+const DEFAULT_TIMERS: Required<SchedulerTimers> = {
+  setInterval: (fn: () => void, ms: number): unknown => setInterval(fn, ms),
+  clearInterval: (handle: unknown): void => { clearInterval(handle as Parameters<typeof clearInterval>[0]) },
+  setTimeout: (fn: () => void, ms: number): unknown => setTimeout(fn, ms),
+  clearTimeout: (handle: unknown): void => { clearTimeout(handle as Parameters<typeof clearTimeout>[0]) },
+}
+
 /**
  * The cron scheduler.
  */
 export class SchedulerService {
   private handle: unknown
-  private catchup: ReturnType<typeof setTimeout> | undefined
+  private catchup: unknown
+  private timers: Required<SchedulerTimers> = DEFAULT_TIMERS
 
   /** @param deps - store + execution + clock. */
   constructor(private readonly deps: SchedulerDeps) {}
 
   /** Start ticking. */
   start(): void {
-    const timers = this.deps.timers ?? {
-      setInterval: (fn: () => void, ms: number) => setInterval(fn, ms),
-      clearInterval: (handle: unknown) => clearInterval(handle as ReturnType<typeof setInterval>),
-    }
-    this.handle = timers.setInterval(() => { void this.tick() }, TICK_MS)
+    // Fill optional timer slots from the globals so a legacy injection that
+    // only carries the interval pair still works end to end.
+    this.timers = this.deps.timers === undefined ? DEFAULT_TIMERS : { ...DEFAULT_TIMERS, ...this.deps.timers }
+    // A tick rejection (disk error inside a mutation) must never surface as
+    // an unhandled rejection — log it and keep the schedule alive.
+    this.handle = this.timers.setInterval(() => { void this.tick().catch(error => {
+      console.error('[dsh-taskboard] scheduler tick failed:', error)
+    }) }, TICK_MS)
     // Catch up promptly on host restart: run one tick soon after start. The
-    // handle is cleared on dispose so a torn-down scheduler never fires.
-    this.catchup = setTimeout(() => { void this.tick() }, 3_000)
+    // handles are cleared on dispose so a torn-down scheduler never fires.
+    this.catchup = this.timers.setTimeout(() => { void this.tick().catch(error => {
+      console.error('[dsh-taskboard] scheduler tick failed:', error)
+    }) }, 3_000)
   }
 
   /** Stop ticking. */
   dispose(): void {
     if (this.catchup !== undefined) {
-      clearTimeout(this.catchup)
+      this.timers.clearTimeout(this.catchup)
       this.catchup = undefined
     }
     if (this.handle === undefined) return
-    const timers = this.deps.timers ?? { clearInterval: (h: unknown) => clearInterval(h as ReturnType<typeof setInterval>) }
-    timers.clearInterval(this.handle)
+    this.timers.clearInterval(this.handle)
     this.handle = undefined
   }
 
@@ -74,49 +91,58 @@ export class SchedulerService {
     await this.deps.store.load()
     const now = this.deps.now()
     const ledger: TaskLedger = this.deps.store.snapshot()
-    const atCapacity = this.deps.execution.inFlight() >= (this.deps.maxConcurrent ?? DEFAULT_MAX_CONCURRENT)
     for (const task of ledger.tasks) {
       if (task.execution.mode !== 'scheduled' || task.execution.cron === undefined) continue
       if (task.execution.nextRunAt === undefined) continue
       if (task.status === 'in_progress' || task.trashedAt !== undefined) continue
       if (task.execution.nextRunAt > now) continue
-      // At the concurrency cap: leave nextRunAt in the past and retry next
-      // tick — advancing here would silently burn this window.
-      if (atCapacity) continue
+      // At the concurrency cap (S4: checked FRESH per task — runs register
+      // only after agent creation, so a once-per-tick snapshot under-counted
+      // the startup window): leave nextRunAt in the past and retry next tick
+      // — advancing here would silently burn this window.
+      if (this.deps.execution.inFlight() >= (this.deps.maxConcurrent ?? DEFAULT_MAX_CONCURRENT)) continue
       const missed = now - task.execution.nextRunAt > SKIP_AFTER_MS
 
-      // Advance the schedule FIRST (idempotent under re-ticks), then run
-      // unless the window was missed entirely.
-      await this.advance(task.id, now)
+      // Advance the schedule AND record the trigger in ONE mutation (S13:
+      // one revision bump, one broadcast, and the two writes can no longer
+      // straddle a status change), then run unless the window was missed.
+      await this.advanceAndMark(task.id, now, missed ? undefined : task.execution.nextRunAt)
       if (missed) continue
-      const lastTriggeredAt = task.execution.nextRunAt
-      await this.markTriggered(task.id, lastTriggeredAt)
       await this.deps.execution.run(task.id, 'scheduled').catch(error => {
         console.error('[dsh-taskboard] scheduled run failed:', error)
       })
     }
   }
 
-  /** Recompute and persist the next run for one scheduled task. */
-  private async advance(taskId: string, now: number): Promise<void> {
+  /**
+   * Recompute the next run and record the trigger instant for one scheduled
+   * task, in one serial-queue mutation. S12: a cron that can no longer match
+   * anything within the 4-year scan window (only reachable through a
+   * hand-edited ledger — every normal entry point validates) would otherwise
+   * leave nextRunAt in the past and spin a full ~2M-iteration scan every
+   * tick; it is cleared with a system comment instead of dying silently.
+   */
+  private async advanceAndMark(taskId: string, now: number, triggeredAt: number | undefined): Promise<void> {
     await this.deps.store.mutate('task-updated', (ledger) => {
       const task = ledger.tasks.find(t => t.id === taskId)
       if (task === undefined || task.execution.cron === undefined) return undefined
+      if (task.status === 'in_progress' || task.trashedAt !== undefined) return undefined
       const match = parseCron(task.execution.cron)
       const next = match === null ? undefined : nextCronTime(match, now) ?? undefined
-      if (next === undefined) return undefined
+      if (next === undefined) {
+        const deadCron = task.execution.cron
+        task.execution.cron = undefined
+        task.execution.nextRunAt = undefined
+        task.comments.push({
+          id: newCommentId(),
+          body: normalizeBody(`[系统] 定时表达式 ${deadCron} 在 4 年内没有可触发时间，已停用定时；请修正 cron 后重新开启。`),
+          version: 1,
+          createdAt: now,
+        })
+        return [task]
+      }
       task.execution.nextRunAt = next
-      return [task]
-    })
-  }
-
-  /** Record the trigger instant on the task. */
-  private async markTriggered(taskId: string, at: number | undefined): Promise<void> {
-    if (at === undefined) return
-    await this.deps.store.mutate('task-updated', (ledger) => {
-      const task = ledger.tasks.find(t => t.id === taskId)
-      if (task === undefined) return undefined
-      task.execution.lastTriggeredAt = at
+      if (triggeredAt !== undefined) task.execution.lastTriggeredAt = triggeredAt
       return [task]
     })
   }

package/src/host/sdk.ts

@@ -141,7 +141,18 @@ function validateValue(schema: RawSchema, value: unknown, path: string): string[
     }
     return violations
   }
-  return matchesScalarType(value, schema.type) ? [] : [`${path} must be ${schema.type}`]
+  if (!matchesScalarType(value, schema.type)) return [`${path} must be ${schema.type}`]
+  // T10: enum/const are compiled into the schema — validate them at runtime
+  // too, so the "pre-validates the same way" promise holds for every node.
+  const enumValues = schema.enum as unknown[] | undefined
+  if (enumValues !== undefined && !enumValues.some(v => v === value)) {
+    return [`${path} must be one of ${enumValues.map(String).join(', ')}`]
+  }
+  const constValue = (schema as { const?: unknown }).const
+  if (constValue !== undefined && constValue !== value) {
+    return [`${path} must be ${String(constValue)}`]
+  }
+  return []
 }
 
 /** Options shape we consume (a structural subset of the SDK's defineTool). */

package/src/host/store.ts

@@ -6,11 +6,12 @@
  *
  * @module dsh-taskboard/host/store
  */
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { mkdir, open, readFile, rename } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import {
   LEDGER_SCHEMA_VERSION,
   emptyLedger,
+  isPlausibleTaskRecord,
   pruneExecutions,
   type TaskLedger,
   type TaskRecord,
@@ -23,7 +24,7 @@ export interface LedgerChange {
   /** The mutated tasks, if any (a comment purge may touch none). */
   tasks: readonly TaskRecord[]
   /** What kind of mutation this was (for SSE event naming later). */
-  kind: 'task-created' | 'task-updated' | 'task-moved' | 'task-deleted' | 'comment-added' | 'execution-recorded'
+  kind: 'task-created' | 'task-updated' | 'task-moved' | 'task-deleted' | 'comment-added' | 'execution-recorded' | 'settings-updated' | 'ledger-replaced'
 }
 
 /** Options for {@link TaskStore}. */
@@ -56,7 +57,20 @@ export class TaskStore {
       const raw = await readFile(this.file, 'utf8')
       const parsed = JSON.parse(raw) as TaskLedger
       if (typeof parsed.revision === 'number' && Array.isArray(parsed.tasks)) {
-        const tasks = parsed.tasks as TaskRecord[]
+        // S11: trust no record wholesale — drop structurally broken entries
+        // (including R4's traversal-shaped ids from a hand-edited file) with
+        // a notice instead of letting them reach the path-building layers.
+        const plausible: TaskRecord[] = []
+        for (const entry of parsed.tasks as unknown[]) {
+          if (!isPlausibleTaskRecord(entry)) {
+            const rawId = (entry as { id?: unknown })?.id
+            const id = typeof rawId === 'string' ? rawId.slice(0, 60) : String(rawId)
+            console.warn('[dsh-taskboard] dropping implausible ledger entry on load:', id)
+            continue
+          }
+          plausible.push(entry as TaskRecord)
+        }
+        const tasks = plausible
         // Migration from pre-claim-field ledgers: an agent-held in_progress
         // task carried its holder in updatedBy — backfill the explicit claim
         // fields so the hold survives user edits (updatedBy is audit-only).
@@ -131,7 +145,9 @@ export class TaskStore {
       const draft: TaskLedger = structuredClone(this.ledger)
       const changed = mutator(draft)
       if (changed === undefined) {
-        return { ledger: this.ledger, changed: [] }
+        // S9 parity: even a no-op mutation hands out a frozen clone — never
+        // the live internal ledger.
+        return { ledger: deepFreeze(structuredClone(this.ledger)), changed: [] }
       }
       // Retention cap: every committed mutation re-checks the touched tasks,
       // so execution history can never grow unbounded (SSE state payload).
@@ -146,11 +162,31 @@ export class TaskStore {
           fn(change)
         } catch { /* subscriber errors never abort the write */ }
       }
-      return { ledger: draft, changed }
+      // S9: hand out frozen clones — the return value used to BE the new
+      // internal ledger; callers must never mutate internal state in place.
+      return {
+        ledger: deepFreeze(structuredClone(draft)),
+        changed: changed.map(t => deepFreeze(structuredClone(t))),
+      }
     }
     const result = (this.queue = this.queue.then(run, run)) as ReturnType<typeof run>
     return result
   }
+
+  /**
+   * Run a read INSIDE the serial queue (R3): observes exactly the ledger
+   * state after all previously enqueued mutations — immune to the
+   * write-then-publish window around `mutate`'s persistence. Read-only: the
+   * callback receives a frozen deep clone and nothing is written.
+   */
+  async read<T>(fn: (ledger: TaskLedger) => T): Promise<T> {
+    const run = async (): Promise<T> => {
+      await this.load()
+      return fn(deepFreeze(structuredClone(this.ledger)))
+    }
+    const result = (this.queue = this.queue.then(run, run)) as Promise<T>
+    return result
+  }
 }
 
 /** Recursively freeze a plain-data value (defense in depth for handed-out snapshots). */
@@ -164,10 +200,20 @@ function deepFreeze<T>(value: T): T {
   return value
 }
 
-/** Atomic file persist: write temp, then rename over the target. */
+/**
+ * Atomic file persist: write temp, fsync, then rename over the target (S10:
+ * without the sync, a power loss after rename can leave a zero-length file —
+ * the next load would quarantine the ledger and start empty).
+ */
 async function persistAtomic(file: string, contents: string): Promise<void> {
   await mkdir(dirname(file), { recursive: true })
   const temp = join(dirname(file), `.${Math.random().toString(36).slice(2)}.tmp`)
-  await writeFile(temp, contents, 'utf8')
+  const fh = await open(temp, 'w')
+  try {
+    await fh.writeFile(contents, 'utf8')
+    await fh.sync()
+  } finally {
+    await fh.close()
+  }
   await rename(temp, file)
 }

package/src/host/templates.ts

@@ -93,13 +93,19 @@ export class TemplateStore {
     this.loaded = true
   }
 
-  /** Atomic persist (temp + rename), same discipline as the ledger. */
+  /** Atomic persist (temp + fsync + rename — S10, same discipline as the ledger). */
   private async persist(templates: TaskTemplate[]): Promise<void> {
-    const { mkdir, writeFile, rename } = await import('node:fs/promises')
+    const { mkdir, open, rename } = await import('node:fs/promises')
     const { dirname, join } = await import('node:path')
     await mkdir(dirname(this.file), { recursive: true })
     const temp = join(dirname(this.file), `.${Math.random().toString(36).slice(2)}.tmp`)
-    await writeFile(temp, JSON.stringify({ templates }, null, 2), 'utf8')
+    const fh = await open(temp, 'w')
+    try {
+      await fh.writeFile(JSON.stringify({ templates }, null, 2), 'utf8')
+      await fh.sync()
+    } finally {
+      await fh.close()
+    }
     await rename(temp, this.file)
   }
 
@@ -120,6 +126,9 @@ export class TemplateStore {
     if (name.length === 0 || name.length > 60) throw new Error('模板名必须 1..60 字符')
     const now = Date.now()
     const existing = input.id !== undefined ? templates.find(t => t.id === input.id) : undefined
+    // T12: built-ins are factory content — editable only by delete + recreate
+    // (deleting stays allowed), never silently overwritten in place.
+    if (existing?.builtin === true) throw new Error('内置模板不可覆盖；可删除后另建，或以新名称存为新模板')
     const stored: TaskTemplate = existing !== undefined
       ? { ...existing, name, task: input.task, updatedAt: now }
       : { id: input.id ?? newTemplateId(), name, task: input.task, createdAt: now, updatedAt: now }