create-windy 0.1.0

package/template/apps/server/src/scheduler/execution-context.ts

@@ -0,0 +1,24 @@
+import type { RequestActor } from "../guards.js";
+import type { ScheduledTaskDefinition, ScheduledTaskRun } from "./types.js";
+
+export type ManualTriggerResult =
+  | { ok: false; reason: "not-found" | "busy" | string }
+  | { ok: true; run: ScheduledTaskRun };
+
+export function schedulerPolicy(definition: ScheduledTaskDefinition) {
+  return {
+    taskKey: definition.key,
+    permission: { permissionKey: definition.permissionKey },
+    feature: definition.feature,
+  };
+}
+
+export function schedulerActor(permissionKey: string): RequestActor {
+  return {
+    id: "system_scheduler",
+    type: "service",
+    name: "平台定时任务执行器",
+    roleCodes: ["system"],
+    permissionKeys: [permissionKey],
+  };
+}

package/template/apps/server/src/scheduler/execution-recorder.ts

@@ -0,0 +1,101 @@
+import type { AuditEvent } from "@windy/shared";
+import type { RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { schedulerAuditEvent } from "./audit.js";
+import type { SchedulerRepository } from "./repository.js";
+import { sanitizeExecutionError } from "./sensitive-text.js";
+import type {
+  ScheduledTaskDefinition,
+  ScheduledTaskRun,
+  SchedulerClock,
+  SchedulerTickResult,
+} from "./types.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export class SchedulerExecutionRecorder {
+  private readonly denialReasons = new Map<string, string>();
+
+  constructor(
+    private readonly repository: SchedulerRepository,
+    private readonly runtime: ServerRuntime,
+    private readonly clock: SchedulerClock,
+  ) {}
+
+  async success(
+    run: ScheduledTaskRun,
+    definition: ScheduledTaskDefinition,
+    context: RequestGuardContext,
+    value: Record<string, unknown> | void,
+  ) {
+    this.denialReasons.delete(run.taskKey);
+    const completed = await this.repository.complete(run.id, {
+      status: "succeeded",
+      finishedAt: this.clock.now(),
+      result: value || undefined,
+    });
+    if (run.trigger === "scheduled" && definition.isIdleResult?.(value)) {
+      await this.repository.discardRun(run.id);
+      return completed;
+    }
+    this.record(context, completed, "task.execute", "success");
+    return completed;
+  }
+
+  async failure(
+    run: ScheduledTaskRun,
+    definition: ScheduledTaskDefinition,
+    context: RequestGuardContext,
+    error: unknown,
+  ) {
+    this.denialReasons.delete(run.taskKey);
+    const finishedAt = this.clock.now();
+    const retry = run.attempt < definition.maxAttempts;
+    const completed = await this.repository.complete(run.id, {
+      status: retry ? "retry-pending" : "failed",
+      finishedAt,
+      nextAttemptAt: retry
+        ? new Date(finishedAt.getTime() + definition.retryDelaySeconds * 1_000)
+        : undefined,
+      error: sanitizeExecutionError(error),
+    });
+    this.record(context, completed, "task.execute", "failure");
+    return completed;
+  }
+
+  denied(context: RequestGuardContext, run: ScheduledTaskRun, reason: string) {
+    if (this.denialReasons.get(run.taskKey) === reason) return;
+    this.denialReasons.set(run.taskKey, reason);
+    this.record(context, run, "task.execute", "denied");
+  }
+
+  trigger(context: RequestGuardContext, run: ScheduledTaskRun) {
+    return this.runtime.auditSink.recordCriticalEvent(
+      schedulerAuditEvent(
+        context,
+        run,
+        "task.trigger",
+        "success",
+        this.clock.now(),
+      ),
+    );
+  }
+
+  count(run: ScheduledTaskRun, result: SchedulerTickResult) {
+    if (run.status === "blocked") result.blocked += 1;
+    if (run.status === "failed" || run.status === "retry-pending") {
+      result.failed += 1;
+    }
+  }
+
+  private record(
+    context: RequestGuardContext,
+    run: ScheduledTaskRun,
+    action: "task.trigger" | "task.execute",
+    outcome: AuditEvent["outcome"],
+  ) {
+    this.runtime.auditSink.recordEvent(
+      schedulerAuditEvent(context, run, action, outcome, this.clock.now()),
+    );
+  }
+}

package/template/apps/server/src/scheduler/feature-preflight.ts

@@ -0,0 +1,40 @@
+import type { createServerRuntime } from "../runtime.js";
+import type { RequestActor } from "../guards.js";
+import type { ScheduledTaskDefinition, StoredScheduledTask } from "./types.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export function isTaskDue(task: StoredScheduledTask, now: Date) {
+  return (
+    task.enabled &&
+    task.status === "active" &&
+    task.nextRunAt <= now.toISOString()
+  );
+}
+
+export async function isScheduledFeatureActive(
+  runtime: ServerRuntime,
+  definition: ScheduledTaskDefinition,
+) {
+  const actor: RequestActor = {
+    id: "system_scheduler",
+    type: "service",
+    name: "平台定时任务执行器",
+    roleCodes: ["system"],
+    permissionKeys: [definition.permissionKey],
+  };
+  try {
+    const context = await runtime.createGuardContextForActor(
+      new Request(
+        `http://scheduler.local/tasks/${encodeURIComponent(definition.key)}`,
+      ),
+      actor,
+    );
+    if (context.license?.restricted) return true;
+    const feature = await runtime.resolveFeature(context, definition.feature);
+    return feature.enabled && feature.visible === "visible";
+  } catch {
+    // License / runtime 读取异常仍进入既有失败与重试链路，保留可观测性。
+    return true;
+  }
+}

package/template/apps/server/src/scheduler/history.ts

@@ -0,0 +1,22 @@
+import type { PageResult, SchedulerRunHistoryItem } from "@windy/shared";
+import type { SchedulerRepository } from "./repository.js";
+import { toRunSummary } from "./overview.js";
+
+export async function listSchedulerRunHistory(
+  repository: SchedulerRepository,
+  page: number,
+  pageSize: number,
+): Promise<PageResult<SchedulerRunHistoryItem>> {
+  const [result, tasks] = await Promise.all([
+    repository.listRunsPage(page, pageSize),
+    repository.listTasks(),
+  ]);
+  const labels = new Map(tasks.map((task) => [task.key, task.label]));
+  return {
+    ...result,
+    items: result.items.map((run) => ({
+      ...toRunSummary(run),
+      taskLabel: labels.get(run.taskKey) || "已移除任务",
+    })),
+  };
+}

package/template/apps/server/src/scheduler/overview.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { buildSchedulerOperationsSnapshot } from "./overview.js";
+import type { ScheduledTaskRun, StoredScheduledTask } from "./types.js";
+
+const task: StoredScheduledTask = {
+  key: "system.scheduler.health-snapshot",
+  label: "调度器健康快照",
+  featureKey: "system.scheduler",
+  permissionKey: "system.scheduler.manage",
+  intervalSeconds: 300,
+  maxAttempts: 3,
+  retryDelaySeconds: 30,
+  enabled: true,
+  status: "active",
+  nextRunAt: "2026-07-10T00:20:00.000Z",
+  lastRunAt: "2026-07-10T00:00:00.000Z",
+};
+
+describe("scheduler operations overview", () => {
+  test("stale 只派生观察状态，不改变 running 执行记录", () => {
+    const run = runningRun();
+    const snapshot = buildSchedulerOperationsSnapshot(
+      [task],
+      [run],
+      new Set([task.key]),
+      new Date("2026-07-10T00:20:00.000Z"),
+      900,
+    );
+
+    expect(snapshot.stalePolicy).toEqual({
+      mode: "observe-only",
+      thresholdSeconds: 900,
+      action: "manual-intervention",
+    });
+    expect(snapshot.tasks[0]?.observability).toMatchObject({
+      state: "stale",
+      stale: true,
+      runningSeconds: 1_200,
+    });
+    expect(run.status).toBe("running");
+    expect(run.finishedAt).toBeUndefined();
+  });
+
+  test("最近错误摘要会脱敏并限制长度", () => {
+    const run: ScheduledTaskRun = {
+      ...runningRun(),
+      status: "retry-pending",
+      finishedAt: "2026-07-10T00:00:01.000Z",
+      nextAttemptAt: "2026-07-10T00:01:00.000Z",
+      error: `password="plain" accessToken=abc apiKey=key clientSecret=secret Bearer bearer-value ${"x".repeat(400)}`,
+      result: { token: "result-must-not-leak" },
+    };
+    const snapshot = buildSchedulerOperationsSnapshot(
+      [task],
+      [run],
+      new Set([task.key]),
+      new Date("2026-07-10T00:00:10.000Z"),
+      900,
+    );
+    const summary = snapshot.recentRuns[0]?.errorSummary || "";
+
+    expect(summary).toContain("password=[REDACTED]");
+    expect(summary).toContain("accessToken=[REDACTED]");
+    expect(summary).toContain("apiKey=[REDACTED]");
+    expect(summary).toContain("clientSecret=[REDACTED]");
+    expect(summary).toContain("Bearer [REDACTED]");
+    expect(summary).not.toContain("plain");
+    expect(summary).not.toContain("bearer-value");
+    expect(summary.length).toBeLessThanOrEqual(240);
+    expect(snapshot.recentRuns[0]).not.toHaveProperty("result");
+    expect(snapshot.tasks[0]?.observability).toMatchObject({
+      state: "retry-pending",
+      retryPendingCount: 1,
+    });
+  });
+});
+
+function runningRun(): ScheduledTaskRun {
+  return {
+    id: "run_1",
+    taskKey: task.key,
+    trigger: "manual",
+    status: "running",
+    attempt: 1,
+    requestedBy: "user_1",
+    scheduledFor: "2026-07-10T00:00:00.000Z",
+    startedAt: "2026-07-10T00:00:00.000Z",
+  };
+}

package/template/apps/server/src/scheduler/overview.ts

@@ -0,0 +1,125 @@
+import type {
+  SchedulerObservedState,
+  SchedulerOperationsSnapshot,
+  SchedulerRunSummary,
+} from "@windy/shared";
+import { sanitizeSchedulerText } from "./sensitive-text.js";
+import type { ScheduledTaskRun, StoredScheduledTask } from "./types.js";
+
+const ERROR_SUMMARY_LIMIT = 240;
+
+export function buildSchedulerOperationsSnapshot(
+  tasks: StoredScheduledTask[],
+  runs: ScheduledTaskRun[],
+  registeredKeys: ReadonlySet<string>,
+  now: Date,
+  staleThresholdSeconds: number,
+): SchedulerOperationsSnapshot {
+  const registeredTasks = tasks.filter(({ key }) => registeredKeys.has(key));
+  const runSummaries = runs.map(toRunSummary);
+  const taskSnapshots = registeredTasks.map((task) => {
+    const taskRuns = runs.filter(({ taskKey }) => taskKey === task.key);
+    const running = taskRuns.find(({ status }) => status === "running");
+    const retryPending = taskRuns.filter(
+      ({ status }) => status === "retry-pending",
+    );
+    const runningSeconds = running
+      ? Math.max(
+          0,
+          Math.floor((now.getTime() - Date.parse(running.startedAt)) / 1_000),
+        )
+      : undefined;
+    const stale =
+      runningSeconds !== undefined && runningSeconds >= staleThresholdSeconds;
+    const latestRun = taskRuns[0] ? toRunSummary(taskRuns[0]) : undefined;
+
+    return {
+      definition: {
+        source: "code-registered" as const,
+        key: task.key,
+        label: task.label,
+        description: task.description,
+        featureKey: task.featureKey,
+        permissionKey: task.permissionKey,
+        intervalSeconds: task.intervalSeconds,
+        maxAttempts: task.maxAttempts,
+        retryDelaySeconds: task.retryDelaySeconds,
+      },
+      persistence: {
+        enabled: task.enabled,
+        status: task.status,
+        nextRunAt: task.nextRunAt,
+        lastRunAt: task.lastRunAt,
+      },
+      observability: {
+        state: observedState(latestRun?.status, Boolean(running), stale),
+        runningSeconds,
+        stale,
+        staleThresholdSeconds,
+        retryPendingCount: retryPending.length,
+        nextRetryAt: retryPending
+          .map(({ nextAttemptAt }) => nextAttemptAt)
+          .filter((value): value is string => Boolean(value))
+          .sort()[0],
+      },
+      latestRun,
+    };
+  });
+
+  return {
+    generatedAt: now.toISOString(),
+    source: "scheduler",
+    stalePolicy: {
+      mode: "observe-only",
+      thresholdSeconds: staleThresholdSeconds,
+      action: "manual-intervention",
+    },
+    summary: {
+      total: taskSnapshots.length,
+      running: taskSnapshots.filter(
+        ({ observability }) => observability.state === "running",
+      ).length,
+      stale: taskSnapshots.filter(({ observability }) => observability.stale)
+        .length,
+      retryPending: taskSnapshots.filter(
+        ({ observability }) => observability.state === "retry-pending",
+      ).length,
+      failed: taskSnapshots.filter(
+        ({ observability }) => observability.state === "failed",
+      ).length,
+    },
+    tasks: taskSnapshots,
+    recentRuns: runSummaries,
+  };
+}
+
+function observedState(
+  latest: SchedulerRunSummary["status"] | undefined,
+  running: boolean,
+  stale: boolean,
+): SchedulerObservedState {
+  if (stale) return "stale";
+  if (running) return "running";
+  return latest || "idle";
+}
+
+export function toRunSummary(run: ScheduledTaskRun): SchedulerRunSummary {
+  return {
+    id: run.id,
+    taskKey: run.taskKey,
+    trigger: run.trigger,
+    status: run.status,
+    attempt: run.attempt,
+    requestedBy: run.requestedBy,
+    scheduledFor: run.scheduledFor,
+    startedAt: run.startedAt,
+    finishedAt: run.finishedAt,
+    nextAttemptAt: run.nextAttemptAt,
+    errorSummary: safeErrorSummary(run.error),
+  };
+}
+
+export function safeErrorSummary(error: string | undefined) {
+  if (!error) return undefined;
+  return sanitizeSchedulerText(error, ERROR_SUMMARY_LIMIT);
+}

package/template/apps/server/src/scheduler/recovery-conflict.ts

@@ -0,0 +1,19 @@
+import type { StaleRunRecovery, StaleRunRecoveryConflict } from "./types.js";
+
+export function staleRecoveryConflict(
+  run:
+    | { taskKey: string; status: string; startedAt: string | Date }
+    | undefined,
+  recovery: StaleRunRecovery,
+): StaleRunRecoveryConflict | undefined {
+  if (!run) return "not-found";
+  if (run.taskKey !== recovery.taskKey) return "task-mismatch";
+  if (run.status !== "running") return "not-running";
+  const startedAt =
+    run.startedAt instanceof Date ? run.startedAt : new Date(run.startedAt);
+  if (startedAt.getTime() !== Date.parse(recovery.expectedStartedAt)) {
+    return "version-mismatch";
+  }
+  if (startedAt > recovery.staleBefore) return "not-stale";
+  return undefined;
+}

package/template/apps/server/src/scheduler/recovery-service.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, test } from "bun:test";
+import { entitlementKey } from "@windy/shared";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createServerRuntime } from "../runtime.js";
+import { InMemorySchedulerRepository } from "./repository.js";
+import { SchedulerService } from "./service.js";
+import type { ScheduledTaskDefinition, SchedulerClock } from "./types.js";
+
+class RecoveryClock implements SchedulerClock {
+  constructor(private current = new Date("2026-07-10T00:00:00.000Z")) {}
+
+  now() {
+    return new Date(this.current);
+  }
+
+  makeStale() {
+    this.current = new Date(this.current.getTime() + 901_000);
+  }
+}
+
+describe("stale scheduler run recovery", () => {
+  test("只终结 stale run，不执行 handler、重试或泄漏敏感理由", async () => {
+    let executions = 0;
+    const fixture = await createFixture({
+      handler: () => {
+        executions += 1;
+      },
+    });
+    const running = await createStaleRun(fixture);
+
+    const result = await fixture.scheduler.recoverStaleRun(
+      "test.task",
+      running.id,
+      running.startedAt,
+      "确认原进程已经退出，password=secret 不允许自动重跑",
+      await fixture.context(),
+    );
+
+    expect(result).toMatchObject({
+      ok: true,
+      run: {
+        status: "blocked",
+        error:
+          "人工确认恢复：确认原进程已经退出，password=[REDACTED] 不允许自动重跑",
+      },
+    });
+    expect(executions).toBe(0);
+    expect(
+      await fixture.repository.listRetryable(fixture.clock.now()),
+    ).toHaveLength(0);
+    const audit = fixture.runtime.auditSink
+      .list()
+      .filter(({ action }) => action === "task.recover");
+    expect(audit.map(({ outcome }) => outcome)).toEqual(["success", "success"]);
+    expect(audit[0]?.metadata).toMatchObject({
+      phase: "intent",
+      runId: running.id,
+      expectedStartedAt: running.startedAt,
+      automaticRetry: false,
+    });
+    expect(JSON.stringify(audit)).not.toContain("password=secret");
+  });
+
+  test("关键意图审计不可用时保持 running", async () => {
+    const fixture = await createFixture({
+      runtimeOptions: {
+        auditWriter: {
+          write(event, policy) {
+            if (event.action === "task.recover" && policy === "critical") {
+              throw new Error("审计数据库和恢复队列均不可用");
+            }
+          },
+        },
+      },
+    });
+    const running = await createStaleRun(fixture);
+
+    expect(await recover(fixture, running.id, running.startedAt)).toMatchObject(
+      { ok: false, reason: "audit-unavailable" },
+    );
+    expect(await fixture.scheduler.listRuns()).toEqual([
+      expect.objectContaining({ id: running.id, status: "running" }),
+    ]);
+  });
+
+  test("恢复按 License、Entitlement、Feature、RBAC 顺序 fail closed", async () => {
+    let featureReads = 0;
+    const restricted = await createFixture({
+      runtimeOptions: {
+        licenseResolver: {
+          resolve: () => ({
+            entitlements: [entitlementKey("capability.scheduler")],
+            status: "expired",
+            restricted: true,
+          }),
+        },
+        featureResolver: {
+          resolve: (key) => {
+            featureReads += 1;
+            return { key, enabled: true, visible: "visible" };
+          },
+        },
+      },
+    });
+    const restrictedRun = await createStaleRun(restricted);
+    expect(
+      await recover(restricted, restrictedRun.id, restrictedRun.startedAt),
+    ).toMatchObject({ ok: false, detail: "license-restricted" });
+    expect(featureReads).toBe(0);
+
+    const unlicensed = await createFixture({ licensed: false });
+    const unlicensedRun = await createStaleRun(unlicensed);
+    expect(
+      await recover(unlicensed, unlicensedRun.id, unlicensedRun.startedAt),
+    ).toMatchObject({ ok: false, detail: "entitlement-not-granted" });
+
+    const disabled = await createFixture({
+      runtimeOptions: {
+        featureResolver: {
+          resolve: (key) => ({ key, enabled: false, visible: "visible" }),
+        },
+      },
+    });
+    const disabledRun = await createStaleRun(disabled);
+    expect(
+      await recover(disabled, disabledRun.id, disabledRun.startedAt),
+    ).toMatchObject({ ok: false, detail: "feature-disabled" });
+
+    const denied = await createFixture({
+      runtimeOptions: {
+        actorResolver: {
+          resolve: () => ({
+            id: "user_readonly",
+            type: "user",
+            name: "只读用户",
+            roleCodes: ["readonly"],
+            permissionKeys: [],
+          }),
+        },
+      },
+    });
+    const deniedRun = await createStaleRun(denied);
+    expect(
+      await recover(denied, deniedRun.id, deniedRun.startedAt),
+    ).toMatchObject({ ok: false, detail: "missing-permission" });
+    for (const fixture of [restricted, unlicensed, disabled, denied]) {
+      expect(fixture.runtime.auditSink.list()).not.toContainEqual(
+        expect.objectContaining({ action: "task.recover" }),
+      );
+      expect(await fixture.scheduler.listRuns()).toEqual([
+        expect.objectContaining({ status: "running" }),
+      ]);
+    }
+  });
+});
+
+interface FixtureOptions {
+  handler?: ScheduledTaskDefinition["handler"];
+  runtimeOptions?: Parameters<typeof createServerRuntime>[1];
+  licensed?: boolean;
+}
+
+async function createFixture(options: FixtureOptions = {}) {
+  const feature = createFoundationSnapshot().features.find(
+    ({ key }) => key === "system.scheduler",
+  );
+  if (!feature) throw new Error("测试缺少 system.scheduler Feature");
+  const runtime = createServerRuntime(
+    {
+      WINDY_DEV_ADMIN_TOKEN: "token",
+      WINDY_LICENSE_ENTITLEMENTS:
+        options.licensed === false ? undefined : "capability.scheduler",
+    },
+    options.runtimeOptions,
+  );
+  const repository = new InMemorySchedulerRepository();
+  const clock = new RecoveryClock();
+  const scheduler = new SchedulerService(
+    repository,
+    [
+      {
+        key: "test.task",
+        label: "测试任务",
+        intervalSeconds: 100,
+        maxAttempts: 3,
+        retryDelaySeconds: 10,
+        permissionKey: "system.scheduler.manage",
+        feature: {
+          ...feature,
+          requiredEntitlement: entitlementKey("capability.scheduler"),
+        },
+        handler: options.handler || (() => undefined),
+      },
+    ],
+    runtime,
+    clock,
+  );
+  await scheduler.initialize();
+  return {
+    runtime,
+    repository,
+    scheduler,
+    clock,
+    context: () =>
+      runtime.createGuardContext(
+        new Request("http://localhost/api/system/scheduler/recover", {
+          headers: { authorization: "Bearer token" },
+        }),
+      ),
+  };
+}
+
+async function createStaleRun(
+  fixture: Awaited<ReturnType<typeof createFixture>>,
+) {
+  const run = await fixture.repository.claimManual(
+    "test.task",
+    "crashed_worker",
+    fixture.clock.now(),
+  );
+  if (!run) throw new Error("应创建崩溃遗留执行");
+  fixture.clock.makeStale();
+  return run;
+}
+
+async function recover(
+  fixture: Awaited<ReturnType<typeof createFixture>>,
+  runId: string,
+  expectedStartedAt: string,
+) {
+  return fixture.scheduler.recoverStaleRun(
+    "test.task",
+    runId,
+    expectedStartedAt,
+    "确认原进程已经退出且本次不可自动重跑",
+    await fixture.context(),
+  );
+}