@stigmer/react 3.5.2 → 3.6.0

package/src/schedule/__tests__/scheduleListFn.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect, vi } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { ScheduleSchema, type Schedule } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { ScheduleListSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/io_pb";
+import { createScheduleListFn, listSchedulesPage } from "../scheduleListFn";
+
+function schedules(count: number): Schedule[] {
+  return Array.from({ length: count }, (_, i) =>
+    create(ScheduleSchema, {
+      metadata: { id: `sch_${i}`, name: `sched-${i}`, slug: `sched-${i}`, org: "acme" },
+    }),
+  );
+}
+
+function clientReturning(items: Schedule[], totalCount: number) {
+  const list = vi
+    .fn()
+    .mockResolvedValue(create(ScheduleListSchema, { items, totalCount }));
+  return { client: { schedule: { list } }, list };
+}
+
+describe("listSchedulesPage", () => {
+  it("sends the org and requested page in the query", async () => {
+    const { client, list } = clientReturning([], 0);
+
+    await listSchedulesPage(client, "acme", { num: 2, size: 10 });
+
+    expect(list).toHaveBeenCalledOnce();
+    const request = list.mock.calls[0][0];
+    expect(request.org).toBe("acme");
+    expect(request.pageInfo?.num).toBe(2);
+    expect(request.pageInfo?.size).toBe(10);
+  });
+
+  it("defaults to page 1, size 20", async () => {
+    const { client, list } = clientReturning([], 0);
+
+    await listSchedulesPage(client, "acme");
+
+    const request = list.mock.calls[0][0];
+    expect(request.pageInfo?.num).toBe(1);
+    expect(request.pageInfo?.size).toBe(20);
+  });
+
+  // Cloud slices server-side: a response never exceeds the page size.
+  it("passes a cloud-shaped page through untouched", async () => {
+    const page = schedules(20);
+    const { client } = clientReturning(page, 50);
+
+    const result = await listSchedulesPage(client, "acme", { num: 2, size: 20 });
+
+    expect(result.items).toHaveLength(20);
+    expect(result.items[0].metadata?.slug).toBe("sched-0");
+    expect(result.totalCount).toBe(50);
+    expect(result.totalPages).toBe(3);
+  });
+
+  it("passes a cloud-shaped final short page through untouched", async () => {
+    const { client } = clientReturning(schedules(10), 50);
+
+    const result = await listSchedulesPage(client, "acme", { num: 3, size: 20 });
+
+    expect(result.items).toHaveLength(10);
+    expect(result.totalPages).toBe(3);
+  });
+
+  // OSS ignores page_info and returns the full org list — an overflowing
+  // response is the tell, and only then is the page sliced locally.
+  it("slices an OSS-shaped full-list response with absolute indices", async () => {
+    const { client } = clientReturning(schedules(50), 50);
+
+    const result = await listSchedulesPage(client, "acme", { num: 2, size: 20 });
+
+    expect(result.items).toHaveLength(20);
+    expect(result.items[0].metadata?.slug).toBe("sched-20");
+    expect(result.items[19].metadata?.slug).toBe("sched-39");
+    expect(result.totalCount).toBe(50);
+    expect(result.totalPages).toBe(3);
+  });
+
+  it("slices the OSS-shaped final short page correctly", async () => {
+    const { client } = clientReturning(schedules(50), 50);
+
+    const result = await listSchedulesPage(client, "acme", { num: 3, size: 20 });
+
+    expect(result.items).toHaveLength(10);
+    expect(result.items[0].metadata?.slug).toBe("sched-40");
+    expect(result.items[9].metadata?.slug).toBe("sched-49");
+  });
+
+  it("returns an empty page with zero totals", async () => {
+    const { client } = clientReturning([], 0);
+
+    const result = await listSchedulesPage(client, "acme");
+
+    expect(result.items).toEqual([]);
+    expect(result.totalCount).toBe(0);
+    expect(result.totalPages).toBe(0);
+  });
+});
+
+describe("createScheduleListFn", () => {
+  it("adapts ListParams to the direct query and back to ListResult", async () => {
+    const { client, list } = clientReturning(schedules(3), 3);
+    const listFn = createScheduleListFn(client);
+
+    const result = await listFn({
+      org: "acme",
+      // No server-side text search for schedules — ignored by contract.
+      query: "ignored",
+      excludePublic: false,
+      crossOrgPublic: false,
+      page: { num: 1, size: 20 },
+    });
+
+    expect(result.totalCount).toBe(3);
+    expect(result.totalPages).toBe(1);
+    expect(result.entries).toHaveLength(3);
+    // Entries are full Schedule protos occupying the SearchResult slot.
+    expect((result.entries[0] as unknown as Schedule).metadata?.slug).toBe("sched-0");
+
+    const request = list.mock.calls[0][0];
+    expect(request.org).toBe("acme");
+    // The query never reaches the wire: ListSchedulesRequest has no
+    // text-search field.
+    expect("query" in request && request.query).toBeFalsy();
+  });
+});

package/src/schedule/__tests__/scheduleState.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { ScheduleSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/spec_pb";
+import { ScheduleStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/status_pb";
+import { deriveScheduleState, formatNextFire } from "../scheduleState";
+
+const enabledSpec = create(ScheduleSpecSchema, {
+  cron: "0 9 * * *",
+  timeZone: "Asia/Kolkata",
+  enabled: true,
+});
+const disabledSpec = create(ScheduleSpecSchema, {
+  cron: "0 9 * * *",
+  timeZone: "Asia/Kolkata",
+  enabled: false,
+});
+const pausedStatus = create(ScheduleStatusSchema, {
+  pausedReason: "5 consecutive failures",
+  consecutiveFailures: 5,
+});
+const healthyStatus = create(ScheduleStatusSchema, {});
+
+describe("deriveScheduleState", () => {
+  // Every lever combination — the two levers must never collapse.
+  const cases = [
+    {
+      name: "enabled + not paused → active",
+      spec: enabledSpec,
+      status: healthyStatus,
+      state: "active",
+      phase: "ready",
+      label: "Active",
+      isPaused: false,
+    },
+    {
+      name: "enabled + paused → paused (platform latch)",
+      spec: enabledSpec,
+      status: pausedStatus,
+      state: "paused",
+      phase: "degraded",
+      label: "Paused",
+      isPaused: true,
+    },
+    {
+      name: "disabled + not paused → disabled (owner switch)",
+      spec: disabledSpec,
+      status: healthyStatus,
+      state: "disabled",
+      phase: "disabled",
+      label: "Disabled",
+      isPaused: false,
+    },
+    {
+      name: "disabled + paused → disabled wins, pause stays visible",
+      spec: disabledSpec,
+      status: pausedStatus,
+      state: "disabled",
+      phase: "disabled",
+      label: "Disabled",
+      isPaused: true,
+    },
+    {
+      name: "missing spec → disabled (fails closed, like the server)",
+      spec: undefined,
+      status: healthyStatus,
+      state: "disabled",
+      phase: "disabled",
+      label: "Disabled",
+      isPaused: false,
+    },
+    {
+      name: "missing status → not paused",
+      spec: enabledSpec,
+      status: undefined,
+      state: "active",
+      phase: "ready",
+      label: "Active",
+      isPaused: false,
+    },
+  ] as const;
+
+  for (const c of cases) {
+    it(c.name, () => {
+      const info = deriveScheduleState(c.spec, c.status);
+      expect(info.state).toBe(c.state);
+      expect(info.phase).toBe(c.phase);
+      expect(info.label).toBe(c.label);
+      expect(info.isPaused).toBe(c.isPaused);
+    });
+  }
+});
+
+describe("formatNextFire", () => {
+  const now = new Date("2026-08-04T10:00:00Z");
+  const at = (offsetMs: number) => new Date(now.getTime() + offsetMs);
+  const MINUTE = 60_000;
+  const HOUR = 60 * MINUTE;
+  const DAY = 24 * HOUR;
+
+  it("renders sub-minute and past instants as 'now' (tick mid-flight)", () => {
+    expect(formatNextFire(at(30_000), now)).toBe("now");
+    expect(formatNextFire(at(-5 * MINUTE), now)).toBe("now");
+  });
+
+  it("renders minutes, hours, and days compactly", () => {
+    expect(formatNextFire(at(5 * MINUTE), now)).toBe("in 5m");
+    expect(formatNextFire(at(59 * MINUTE), now)).toBe("in 59m");
+    expect(formatNextFire(at(3 * HOUR), now)).toBe("in 3h");
+    expect(formatNextFire(at(23 * HOUR), now)).toBe("in 23h");
+    expect(formatNextFire(at(DAY), now)).toBe("in 1d");
+    expect(formatNextFire(at(6 * DAY + 23 * HOUR), now)).toBe("in 6d");
+  });
+
+  it("falls back to a short date beyond a week", () => {
+    const target = at(10 * DAY);
+    // Locale-independent expectation: same formatting call, same options.
+    const expected = target.toLocaleDateString(undefined, {
+      month: "short",
+      day: "numeric",
+    });
+    expect(formatNextFire(target, now)).toBe(expected);
+  });
+
+  it("includes the year when the date crosses a year boundary", () => {
+    const target = new Date("2027-01-15T10:00:00Z");
+    const expected = target.toLocaleDateString(undefined, {
+      month: "short",
+      day: "numeric",
+      year: "numeric",
+    });
+    expect(formatNextFire(target, now)).toBe(expected);
+  });
+});

package/src/schedule/cadence.ts

@@ -0,0 +1,298 @@
+/**
+ * The cadence model behind {@link CadenceField} — a pure, dependency-free
+ * bridge between human-friendly schedule presets and the 5-field cron
+ * grammar the Schedule spec stores.
+ *
+ * Deliberately NOT a cron parser. The platform owns no cron parsing in
+ * either edition — calendar and DST semantics live in the Temporal server
+ * (see stigmer-server's schedule/controller/cron.go, DD-008 D2). This
+ * module only:
+ *
+ *   1. GENERATES cron strings from presets (`cadenceToCron`) — trivial
+ *      string construction, always valid by construction.
+ *   2. RECOGNIZES the exact shapes the builder emits (`cronToCadence`)
+ *      so a stored cron round-trips back into the preset UI; anything
+ *      else falls back to the `custom` preset showing the raw string.
+ *   3. MIRRORS the server's purely lexical validation (`validateCron`,
+ *      `validateTimeZone`) with the same user-facing wording, so the
+ *      form can reject bad input instantly. The server remains the
+ *      authority — its errors surface verbatim on submit.
+ */
+
+// ---------------------------------------------------------------------------
+// Preset model
+// ---------------------------------------------------------------------------
+
+/** A human-friendly cadence, convertible to/from a cron expression. */
+export type CadencePreset =
+  | { readonly kind: "hourly"; readonly minute: number }
+  | { readonly kind: "daily"; readonly hour: number; readonly minute: number }
+  | {
+      readonly kind: "weekly";
+      /** Days of week, cron numbering: 0 = Sunday … 6 = Saturday. */
+      readonly days: readonly number[];
+      readonly hour: number;
+      readonly minute: number;
+    }
+  | {
+      readonly kind: "monthly";
+      /** Day of month, 1–31. Days 29–31 skip months without that day. */
+      readonly day: number;
+      readonly hour: number;
+      readonly minute: number;
+    }
+  | { readonly kind: "custom"; readonly cron: string };
+
+/** Discriminant of {@link CadencePreset}. */
+export type CadenceKind = CadencePreset["kind"];
+
+/** Day-of-week labels indexed by cron numbering (0 = Sunday). */
+export const WEEKDAY_LABELS = [
+  "Sunday",
+  "Monday",
+  "Tuesday",
+  "Wednesday",
+  "Thursday",
+  "Friday",
+  "Saturday",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Preset → cron
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the 5-field cron expression for a preset.
+ *
+ * Output is always valid by construction: numeric fields only,
+ * day-of-week in cron numbering (0 = Sunday). For `custom`, the raw
+ * string is returned as-is — validate it with {@link validateCron}.
+ */
+export function cadenceToCron(preset: CadencePreset): string {
+  switch (preset.kind) {
+    case "hourly":
+      return `${preset.minute} * * * *`;
+    case "daily":
+      return `${preset.minute} ${preset.hour} * * *`;
+    case "weekly": {
+      // Sorted, deduplicated day list keeps the output canonical so
+      // cronToCadence round-trips regardless of selection order.
+      const days = [...new Set(preset.days)].sort((a, b) => a - b);
+      return `${preset.minute} ${preset.hour} * * ${days.join(",")}`;
+    }
+    case "monthly":
+      return `${preset.minute} ${preset.hour} ${preset.day} * *`;
+    case "custom":
+      return preset.cron;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Cron → preset (recognition, not parsing)
+// ---------------------------------------------------------------------------
+
+const HOURLY_RE = /^(\d{1,2}) \* \* \* \*$/;
+const DAILY_RE = /^(\d{1,2}) (\d{1,2}) \* \* \*$/;
+const WEEKLY_RE = /^(\d{1,2}) (\d{1,2}) \* \* (\d(?:,\d)*)$/;
+const MONTHLY_RE = /^(\d{1,2}) (\d{1,2}) (\d{1,2}) \* \*$/;
+
+/**
+ * Recognize a cron expression as one of the builder's presets.
+ *
+ * Only the exact shapes {@link cadenceToCron} emits (plus the
+ * calendar shorthands `@hourly`/`@daily`/`@weekly`/`@monthly`) map to a
+ * structured preset. Everything else — ranges, steps, names, `@yearly`
+ * — is a perfectly valid schedule that this UI simply cannot decompose,
+ * so it round-trips as `custom` with the raw string intact.
+ */
+export function cronToCadence(cron: string): CadencePreset {
+  const normalized = cron.trim().replace(/\s+/g, " ");
+
+  switch (normalized) {
+    case "@hourly":
+      return { kind: "hourly", minute: 0 };
+    case "@daily":
+      return { kind: "daily", hour: 0, minute: 0 };
+    case "@weekly":
+      return { kind: "weekly", days: [0], hour: 0, minute: 0 };
+    case "@monthly":
+      return { kind: "monthly", day: 1, hour: 0, minute: 0 };
+  }
+
+  let m = HOURLY_RE.exec(normalized);
+  if (m) {
+    const minute = Number(m[1]);
+    if (isMinute(minute)) return { kind: "hourly", minute };
+  }
+
+  m = DAILY_RE.exec(normalized);
+  if (m) {
+    const minute = Number(m[1]);
+    const hour = Number(m[2]);
+    if (isMinute(minute) && isHour(hour)) return { kind: "daily", hour, minute };
+  }
+
+  m = WEEKLY_RE.exec(normalized);
+  if (m) {
+    const minute = Number(m[1]);
+    const hour = Number(m[2]);
+    const days = m[3].split(",").map(Number);
+    if (
+      isMinute(minute) &&
+      isHour(hour) &&
+      days.length > 0 &&
+      days.every((d) => d >= 0 && d <= 6) &&
+      new Set(days).size === days.length
+    ) {
+      return { kind: "weekly", days: [...days].sort((a, b) => a - b), hour, minute };
+    }
+  }
+
+  m = MONTHLY_RE.exec(normalized);
+  if (m) {
+    const minute = Number(m[1]);
+    const hour = Number(m[2]);
+    const day = Number(m[3]);
+    if (isMinute(minute) && isHour(hour) && day >= 1 && day <= 31) {
+      return { kind: "monthly", day, hour, minute };
+    }
+  }
+
+  return { kind: "custom", cron };
+}
+
+function isMinute(n: number): boolean {
+  return Number.isInteger(n) && n >= 0 && n <= 59;
+}
+
+function isHour(n: number): boolean {
+  return Number.isInteger(n) && n >= 0 && n <= 23;
+}
+
+// ---------------------------------------------------------------------------
+// Plain-English summary
+// ---------------------------------------------------------------------------
+
+/**
+ * Human-readable summary of a cadence, e.g.
+ * `"Every day at 09:00 (Asia/Kolkata)"`.
+ *
+ * This is a description of the chosen preset, not a computed fire-time
+ * forecast — the platform's next fire time is published by the server
+ * as `status.next_fire_at` after apply.
+ */
+export function describeCadence(
+  preset: CadencePreset,
+  timeZone?: string,
+): string {
+  const zone = timeZone ? ` (${timeZone})` : "";
+  switch (preset.kind) {
+    case "hourly":
+      return `Every hour at minute ${preset.minute}${zone}`;
+    case "daily":
+      return `Every day at ${formatTime(preset.hour, preset.minute)}${zone}`;
+    case "weekly": {
+      const days = [...new Set(preset.days)].sort((a, b) => a - b);
+      const names =
+        days.length === 7
+          ? "day"
+          : listWithAnd(days.map((d) => WEEKDAY_LABELS[d]));
+      return `Every ${names} at ${formatTime(preset.hour, preset.minute)}${zone}`;
+    }
+    case "monthly":
+      return `On day ${preset.day} of every month at ${formatTime(preset.hour, preset.minute)}${zone}`;
+    case "custom":
+      return `Cron “${preset.cron.trim()}”${zone}`;
+  }
+}
+
+/** `9, 5` → `"09:05"` (24-hour clock, zero-padded). */
+export function formatTime(hour: number, minute: number): string {
+  return `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
+}
+
+function listWithAnd(items: readonly string[]): string {
+  if (items.length === 1) return items[0];
+  return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+
+// ---------------------------------------------------------------------------
+// Lexical validation — mirrors stigmer-server schedule/controller/cron.go
+// ---------------------------------------------------------------------------
+
+// The accepted @-shorthands, the field character set, the rejection
+// cases AND the message wording below mirror the server byte-for-byte
+// (Go: cron.go / cron_test.go; Java: ValidateScheduleSpec). A change on
+// any side must change all three, or the instant client feedback drifts
+// from what the server enforces on submit.
+
+const CRON_SHORTHANDS = new Set([
+  "@hourly",
+  "@daily",
+  "@weekly",
+  "@monthly",
+  "@yearly",
+]);
+
+const CRON_FIELD_PATTERN = /^[0-9A-Za-z*,/-]+$/;
+
+/**
+ * Validate a cron expression against the platform's lexical grammar.
+ *
+ * Returns the user-facing error message (identical wording to the
+ * server's) or `null` when the expression is acceptable. Purely
+ * lexical — it does not evaluate calendar semantics.
+ */
+export function validateCron(cron: string): string | null {
+  if (cron.startsWith("CRON_TZ=") || cron.startsWith("TZ=")) {
+    return "spec.cron must not carry a timezone prefix (CRON_TZ=/TZ=) — spec.time_zone is the single timezone authority";
+  }
+
+  if (cron.includes("#")) {
+    return "spec.cron must not contain a comment (#)";
+  }
+
+  if (cron.startsWith("@")) {
+    if (cron.startsWith("@every")) {
+      return "spec.cron must be a calendar expression — @every intervals are not supported";
+    }
+    if (!CRON_SHORTHANDS.has(cron)) {
+      return `spec.cron shorthand "${cron}" is not supported — use @hourly, @daily, @weekly, @monthly, or @yearly, or a 5-field cron expression`;
+    }
+    return null;
+  }
+
+  // Matches Go's strings.Fields: split on runs of whitespace, so
+  // surrounding/duplicate whitespace never produces empty fields.
+  const fields = cron.split(/\s+/).filter((f) => f.length > 0);
+  if (fields.length !== 5) {
+    return `spec.cron must have exactly 5 fields (minute hour day-of-month month day-of-week); got ${fields.length}`;
+  }
+
+  for (const field of fields) {
+    if (!CRON_FIELD_PATTERN.test(field)) {
+      return `spec.cron field "${field}" contains unsupported characters — allowed: digits, names, '*', ',', '-', '/'`;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Validate an IANA time zone name using the runtime's own tz database
+ * (`Intl`), mirroring the server's check against the platform tz
+ * database. Returns the user-facing error message or `null`.
+ *
+ * `"Local"` is rejected explicitly for the same reason the server
+ * rejects it: it is host-dependent, not a zone.
+ */
+export function validateTimeZone(timeZone: string): string | null {
+  const invalid = `spec.time_zone "${timeZone}" is not a valid IANA time zone (e.g. "Asia/Kolkata")`;
+  if (timeZone === "Local") return invalid;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone });
+    return null;
+  } catch {
+    return invalid;
+  }
+}

package/src/schedule/index.ts

@@ -0,0 +1,57 @@
+export { deriveScheduleState, formatNextFire } from "./scheduleState.js";
+export type { ScheduleState, ScheduleStateInfo } from "./scheduleState.js";
+
+export { createScheduleListFn, listSchedulesPage } from "./scheduleListFn.js";
+export type { ScheduleListClient, SchedulePage } from "./scheduleListFn.js";
+
+export { useSchedule } from "./useSchedule.js";
+export type { UseScheduleReturn } from "./useSchedule.js";
+
+export { useScheduleList } from "./useScheduleList.js";
+export type {
+  UseScheduleListOptions,
+  UseScheduleListReturn,
+} from "./useScheduleList.js";
+
+export { useScheduleCount } from "./useScheduleCount.js";
+export type {
+  UseScheduleCountOptions,
+  UseScheduleCountReturn,
+} from "./useScheduleCount.js";
+
+export { useResumeSchedule } from "./useResumeSchedule.js";
+export type { UseResumeScheduleReturn } from "./useResumeSchedule.js";
+
+export { useTriggerSchedule } from "./useTriggerSchedule.js";
+export type { UseTriggerScheduleReturn } from "./useTriggerSchedule.js";
+
+export { useSetScheduleEnabled } from "./useSetScheduleEnabled.js";
+export type { UseSetScheduleEnabledReturn } from "./useSetScheduleEnabled.js";
+
+export { createScheduleColumns } from "./scheduleColumns.js";
+export type { ScheduleColumnsOptions } from "./scheduleColumns.js";
+
+export { ScheduleRowActions } from "./ScheduleRowActions.js";
+export type { ScheduleRowActionsProps } from "./ScheduleRowActions.js";
+
+export { ScheduleDetailView, ScheduleIcon } from "./ScheduleDetailView.js";
+export type { ScheduleDetailViewProps } from "./ScheduleDetailView.js";
+
+export {
+  cadenceToCron,
+  cronToCadence,
+  describeCadence,
+  validateCron,
+  validateTimeZone,
+  WEEKDAY_LABELS,
+} from "./cadence.js";
+export type { CadencePreset, CadenceKind } from "./cadence.js";
+
+export { useCreateSchedule } from "./useCreateSchedule.js";
+export type { UseCreateScheduleReturn } from "./useCreateSchedule.js";
+
+export { CadenceField } from "./CadenceField.js";
+export type { CadenceFieldProps } from "./CadenceField.js";
+
+export { ScheduleForm } from "./ScheduleForm.js";
+export type { ScheduleFormProps } from "./ScheduleForm.js";