@linxin666/dsh-client-ui-task-board 0.1.20 → 0.2.1

package/src/protocol.ts

@@ -0,0 +1,220 @@
+import type { TaskUpdatePatch } from './core/use-cases/task-update.ts'
+import { isTaskPermission, isTaskStatus, type NewTaskInput, type TaskRecord, type TaskStatus } from './core/tasks.ts'
+import { parseLedger } from './core/store.ts'
+
+export const TASK_BOARD_SCHEMA_VERSION = 2 as const
+export const TASK_BOARD_API_PREFIX = '/api/task-board'
+
+export type PowerPhase = 'disabled' | 'idle' | 'acquiring' | 'active' | 'error' | 'unsupported'
+
+export interface TaskBoardPowerSnapshot {
+  platform: string
+  phase: PowerPhase
+  enabled: boolean
+  runningSessions: number
+  armedSchedules: number
+  sessionStateKnown: boolean
+  lastError?: string
+}
+
+export interface TaskBoardSchedulerSnapshot {
+  timeZone: string
+  /** Opaque identity of the current Host ledger generation. */
+  ledgerId?: string
+  lastTickAt?: number
+  error?: string
+}
+
+export interface TaskBoardSnapshot {
+  schemaVersion: typeof TASK_BOARD_SCHEMA_VERSION
+  revision: number
+  tasks: TaskRecord[]
+  scheduler: TaskBoardSchedulerSnapshot
+  power: TaskBoardPowerSnapshot
+}
+
+/** SSE event frame: revision/scheduler/power only, never the task list. */
+export interface TaskBoardEventPayload {
+  revision: number
+  scheduler: TaskBoardSchedulerSnapshot
+  power: TaskBoardPowerSnapshot
+}
+
+export type TaskBoardAction =
+  | { kind: 'import'; sourceId: string; tasks: TaskRecord[] }
+  | { kind: 'create'; id: string; input: NewTaskInput }
+  | { kind: 'update'; taskId: string; patch: TaskUpdatePatch }
+  | { kind: 'delete'; taskId: string }
+  | { kind: 'move'; taskId: string; status: TaskStatus }
+  | { kind: 'archive'; taskId: string }
+  | { kind: 'restore'; taskId: string }
+  | { kind: 'set-schedule'; taskId: string; patch: { enabled?: boolean; cron?: string } }
+  | { kind: 'run'; taskId: string }
+  | { kind: 'rerun'; taskId: string }
+
+export interface TaskBoardActionEnvelope {
+  requestId: string
+  action: TaskBoardAction
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+function exactKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+  return Object.keys(value).every(key => allowed.includes(key))
+}
+
+function optionalString(value: unknown): boolean {
+  return value === undefined || typeof value === 'string'
+}
+
+const FORBIDDEN_IMPORT_FIELDS = new Set(['args', 'command', 'executable', 'powershell', 'shell'])
+
+function hasForbiddenImportField(value: unknown): boolean {
+  if (Array.isArray(value)) return value.some(hasForbiddenImportField)
+  const row = record(value)
+  if (row === undefined) return false
+  return Object.entries(row).some(([key, nested]) => FORBIDDEN_IMPORT_FIELDS.has(key.toLowerCase()) || hasForbiddenImportField(nested))
+}
+
+function optionalFiniteNumber(value: unknown): boolean {
+  return value === undefined || (typeof value === 'number' && Number.isFinite(value))
+}
+
+function validImportedKnownFields(value: Record<string, unknown>): boolean {
+  if (value.schedule !== undefined) {
+    const schedule = record(value.schedule)
+    if (schedule === undefined || typeof schedule.enabled !== 'boolean' || typeof schedule.cron !== 'string') return false
+    if (!optionalFiniteNumber(schedule.nextRunAt) || !optionalFiniteNumber(schedule.lastTriggeredAt)) return false
+  }
+  if (value.executions !== undefined) {
+    if (!Array.isArray(value.executions)) return false
+    for (const item of value.executions) {
+      const execution = record(item)
+      if (execution === undefined || typeof execution.id !== 'string' || !optionalString(execution.sessionId)) return false
+      if (typeof execution.startedAt !== 'number' || !Number.isFinite(execution.startedAt)) return false
+      if (!optionalFiniteNumber(execution.endedAt) || !optionalString(execution.error)) return false
+      if (execution.result !== undefined && !['succeeded', 'failed', 'cancelled'].includes(String(execution.result))) return false
+    }
+  }
+  return true
+}
+
+function importedTask(value: unknown): TaskRecord | undefined {
+  const input = record(value)
+  if (input === undefined || hasForbiddenImportField(input) || !validImportedKnownFields(input)) return undefined
+  const task = parseLedger(JSON.stringify([value]))[0]
+  if (task === undefined) return undefined
+  return {
+    id: task.id,
+    title: task.title,
+    description: task.description,
+    prompt: task.prompt,
+    status: task.status,
+    createdAt: task.createdAt,
+    updatedAt: task.updatedAt,
+    executions: task.executions.map(execution => ({
+      id: execution.id,
+      sessionId: execution.sessionId,
+      startedAt: execution.startedAt,
+      endedAt: execution.endedAt,
+      result: execution.result,
+      error: execution.error,
+    })),
+    ...(task.schedule === undefined ? {} : {
+      schedule: {
+        enabled: task.schedule.enabled,
+        cron: task.schedule.cron,
+        nextRunAt: task.schedule.nextRunAt,
+        lastTriggeredAt: task.schedule.lastTriggeredAt,
+      },
+    }),
+    ...(task.workspaceId === undefined ? {} : { workspaceId: task.workspaceId }),
+    ...(task.mode === undefined ? {} : { mode: task.mode }),
+    ...(task.permission === undefined ? {} : { permission: task.permission }),
+    ...(task.archivedAt === undefined ? {} : { archivedAt: task.archivedAt }),
+  }
+}
+
+function createInput(value: unknown): value is NewTaskInput {
+  const input = record(value)
+  if (input === undefined || !exactKeys(input, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'schedule'])) return false
+  if (typeof input.title !== 'string' || typeof input.description !== 'string' || typeof input.prompt !== 'string') return false
+  if (!optionalString(input.workspaceId) || !optionalString(input.mode)) return false
+  if (input.permission !== undefined && !isTaskPermission(input.permission)) return false
+  if (input.schedule !== undefined) {
+    const schedule = record(input.schedule)
+    if (schedule === undefined || !exactKeys(schedule, ['enabled', 'cron'])) return false
+    if (typeof schedule.enabled !== 'boolean' || typeof schedule.cron !== 'string') return false
+  }
+  return true
+}
+
+function updatePatch(value: unknown): boolean {
+  const patch = record(value)
+  if (patch === undefined || !exactKeys(patch, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission'])) return false
+  for (const key of ['title', 'description', 'prompt', 'workspaceId', 'mode'] as const) {
+    if (!optionalString(patch[key])) return false
+  }
+  return patch.permission === undefined || isTaskPermission(patch.permission)
+}
+
+function schedulePatch(value: unknown): boolean {
+  const patch = record(value)
+  return patch !== undefined
+    && exactKeys(patch, ['enabled', 'cron'])
+    && (patch.enabled === undefined || typeof patch.enabled === 'boolean')
+    && (patch.cron === undefined || typeof patch.cron === 'string')
+}
+
+export function parseActionEnvelope(value: unknown): TaskBoardActionEnvelope | undefined {
+  const envelope = record(value)
+  if (envelope === undefined || !exactKeys(envelope, ['requestId', 'action'])) return undefined
+  if (typeof envelope.requestId !== 'string' || envelope.requestId.trim() === '' || envelope.requestId.length > 256) return undefined
+  const action = record(envelope.action)
+  if (action === undefined || typeof action.kind !== 'string') return undefined
+  const taskId = typeof action.taskId === 'string' && action.taskId !== '' ? action.taskId : undefined
+  switch (action.kind) {
+    case 'import':
+      if (!exactKeys(action, ['kind', 'sourceId', 'tasks'])) return undefined
+      if (typeof action.sourceId !== 'string' || action.sourceId === '' || !Array.isArray(action.tasks)) return undefined
+      {
+        const tasks = action.tasks.map(importedTask)
+        return tasks.every((task): task is TaskRecord => task !== undefined)
+          ? { requestId: envelope.requestId, action: { kind: 'import', sourceId: action.sourceId, tasks } }
+          : undefined
+      }
+    case 'create':
+      if (!exactKeys(action, ['kind', 'id', 'input'])) return undefined
+      return typeof action.id === 'string' && action.id !== '' && createInput(action.input)
+        ? { requestId: envelope.requestId, action: action as unknown as Extract<TaskBoardAction, { kind: 'create' }> }
+        : undefined
+    case 'update':
+      if (!exactKeys(action, ['kind', 'taskId', 'patch'])) return undefined
+      return taskId !== undefined && updatePatch(action.patch)
+        ? { requestId: envelope.requestId, action: action as unknown as Extract<TaskBoardAction, { kind: 'update' }> }
+        : undefined
+    case 'set-schedule':
+      if (!exactKeys(action, ['kind', 'taskId', 'patch'])) return undefined
+      return taskId !== undefined && schedulePatch(action.patch)
+        ? { requestId: envelope.requestId, action: action as unknown as Extract<TaskBoardAction, { kind: 'set-schedule' }> }
+        : undefined
+    case 'move':
+      if (!exactKeys(action, ['kind', 'taskId', 'status'])) return undefined
+      return taskId !== undefined && isTaskStatus(action.status)
+        ? { requestId: envelope.requestId, action: action as unknown as Extract<TaskBoardAction, { kind: 'move' }> }
+        : undefined
+    case 'delete':
+    case 'archive':
+    case 'restore':
+    case 'run':
+    case 'rerun':
+      if (!exactKeys(action, ['kind', 'taskId'])) return undefined
+      return taskId === undefined ? undefined : { requestId: envelope.requestId, action: action as TaskBoardAction }
+    default:
+      return undefined
+  }
+}

package/lib/types/core/scheduler.d.ts

@@ -1,70 +0,0 @@
-import type { TaskRecord } from './tasks.ts';
-/** Everything the scheduler needs from its host (the board controller). */
-export interface SchedulerDeps {
-    /** Read the current task ledger (the controller snapshot). */
-    tasks(): readonly TaskRecord[];
-    /**
-     * Re-sync the task ledger from its persisted source before the tick decides
-     * what is due. The wiring passes the controller's store reload so a task
-     * deleted elsewhere can never be fired from a stale in-memory copy.
-     * Optional: absent in pure in-memory harnesses.
-     */
-    refresh?: () => void;
-    /** Clock; defaults to Date.now in the controller wiring. */
-    now(): number;
-    /** Trigger one task's real execution (the controller's runTask); resolves
-     *  true when the run was accepted, false when rejected (e.g. the task is
-     *  already running). */
-    runTask(id: string): Promise<boolean>;
-    /** Persist a rolled-forward schedule (next due + this trigger instant). */
-    applySchedule(id: string, nextRunAt: number | undefined, lastTriggeredAt: number | undefined): void;
-    /** Tick cadence; defaults to 60_000 ms. */
-    tickMs?: number;
-    /**
-     * Gate: while false the tick no-ops (e.g. the session list baseline has not
-     * arrived on page load, so executions would fail). Defaults to always ready.
-     */
-    ready?: () => boolean;
-    /** Environment listeners for tab-visibility recovery (browser only). */
-    environment?: {
-        addEventListener(type: 'visibilitychange', listener: () => void): void;
-        removeEventListener(type: 'visibilitychange', listener: () => void): void;
-    };
-}
-/**
- * The schedule heartbeat (see module doc). `tick` is public so tests and
- * callers can drive a check without waiting for the interval.
- */
-export declare class SchedulerService {
-    private readonly deps;
-    private timer;
-    private environmentListener;
-    private disposed;
-    private started;
-    /** Cron expressions that matched no instant in the scan window, per task —
-     *  remembered so a never-matching rule is not re-scanned on every tick. */
-    private readonly unmatchableRepair;
-    /** @param deps - tasks/clock/trigger/apply faces (see {@link SchedulerDeps}). */
-    constructor(deps: SchedulerDeps);
-    /**
-     * 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;
-    /**
-     * 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;
-    /** Stop ticking and drop listeners (idempotent). */
-    dispose(): void;
-    /**
-     * Check every enabled schedule and trigger the due ones. Idempotent per
-     * task per tick: the schedule is rolled forward only after runTask accepts
-     * the run, so a rejected run keeps its due slot and is retried on the next
-     * tick instead of being silently dropped.
-     */
-    tick(): Promise<void>;
-}

package/src/core/scheduler.ts

@@ -1,161 +0,0 @@
-/**
- * Browser-side scheduler: the heartbeat behind scheduled task runs.
- *
- * The board is a pure client plugin with no server channel, so "定时任务"
- * lives in the tab: a timer ticks every minute (plus immediately on tab
- * visibility recovery) and triggers any task whose `schedule.nextRunAt` is
- * due, rolling the schedule forward to the next cron match before triggering
- * so the same tick never double-fires. Missed runs are skipped, never queued:
- * a task still running at its due instant is skipped by the controller's
- * runTask guard and simply waits for the next cron match.
- *
- * A deleted task can never fire again from a stale in-memory copy: every
- * tick first re-reads the persisted ledger through the optional `refresh`
- * hook (the controller reloads its store), so the fire decision and the
- * subsequent roll-forward both run on the freshest persisted truth.
- *
- * 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.
- */
-import { nextRunAtMs } from './schedule.ts'
-import type { TaskRecord } from './tasks.ts'
-
-/** Everything the scheduler needs from its host (the board controller). */
-export interface SchedulerDeps {
-  /** Read the current task ledger (the controller snapshot). */
-  tasks(): readonly TaskRecord[]
-  /**
-   * Re-sync the task ledger from its persisted source before the tick decides
-   * what is due. The wiring passes the controller's store reload so a task
-   * deleted elsewhere can never be fired from a stale in-memory copy.
-   * Optional: absent in pure in-memory harnesses.
-   */
-  refresh?: () => void
-  /** Clock; defaults to Date.now in the controller wiring. */
-  now(): number
-  /** Trigger one task's real execution (the controller's runTask); resolves
-   *  true when the run was accepted, false when rejected (e.g. the task is
-   *  already running). */
-  runTask(id: string): Promise<boolean>
-  /** Persist a rolled-forward schedule (next due + this trigger instant). */
-  applySchedule(id: string, nextRunAt: number | undefined, lastTriggeredAt: number | undefined): void
-  /** Tick cadence; defaults to 60_000 ms. */
-  tickMs?: number
-  /**
-   * Gate: while false the tick no-ops (e.g. the session list baseline has not
-   * arrived on page load, so executions would fail). Defaults to always ready.
-   */
-  ready?: () => boolean
-  /** Environment listeners for tab-visibility recovery (browser only). */
-  environment?: {
-    addEventListener(type: 'visibilitychange', listener: () => void): void
-    removeEventListener(type: 'visibilitychange', listener: () => void): void
-  }
-}
-
-/**
- * The schedule heartbeat (see module doc). `tick` is public so tests and
- * callers can drive a check without waiting for the interval.
- */
-export class SchedulerService {
-  private timer: ReturnType<typeof setInterval> | undefined
-  private environmentListener: (() => void) | undefined
-  private disposed = false
-  private started = false
-  /** Cron expressions that matched no instant in the scan window, per task —
-   *  remembered so a never-matching rule is not re-scanned on every tick. */
-  private readonly unmatchableRepair = new Map<string, string>()
-
-  /** @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.
-   * 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)
-    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
-    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
-    }
-  }
-
-  /**
-   * Check every enabled schedule and trigger the due ones. Idempotent per
-   * task per tick: the schedule is rolled forward only after runTask accepts
-   * the run, so a rejected run keeps its due slot and is retried on the next
-   * tick instead of being silently dropped.
-   */
-  async tick(): Promise<void> {
-    if (this.disposed) return
-    if (this.deps.ready !== undefined && !this.deps.ready()) return
-    // Freshest persisted truth before any fire decision: a task deleted in
-    // another tab (or a stale in-memory copy) must never be triggered.
-    this.deps.refresh?.()
-    const now = this.deps.now()
-    for (const task of this.deps.tasks()) {
-      const schedule = task.schedule
-      if (schedule === undefined || !schedule.enabled) continue
-      if (schedule.nextRunAt === undefined) {
-        // Missing next-run instant (repaired/legacy data): recompute from the
-        // cron expression and wait; an unparseable expression is skipped. A
-        // grammatically valid rule with no match in the window (e.g. Feb 30)
-        // would otherwise re-run the full minute-by-minute scan every tick.
-        if (this.unmatchableRepair.get(task.id) === schedule.cron) continue
-        const repaired = nextRunAtMs(schedule.cron, now)
-        if (repaired === undefined) {
-          this.unmatchableRepair.set(task.id, schedule.cron)
-          continue
-        }
-        this.unmatchableRepair.delete(task.id)
-        this.deps.applySchedule(task.id, repaired, undefined)
-        continue
-      }
-      if (schedule.nextRunAt > now) continue
-      // Advance from the due instant (not this tick's wall-clock) and only
-      // after the run is accepted: a rejected run keeps its due slot.
-      const next = nextRunAtMs(schedule.cron, schedule.nextRunAt)
-      const accepted = await this.deps.runTask(task.id)
-      if (accepted) this.deps.applySchedule(task.id, next, now)
-    }
-  }
-}
-