@dxos/plugin-automation 0.8.4-staging.60fe92afc8 → 0.9.1-main.c7dcc2e112

package/src/components/CronBuilder/cron.ts

@@ -0,0 +1,138 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import cronstrue from 'cronstrue';
+
+import type { CronSpecType, DayOfWeek } from './schema';
+
+const DOW_MAP: Record<DayOfWeek, number> = {
+  sun: 0,
+  mon: 1,
+  tue: 2,
+  wed: 3,
+  thu: 4,
+  fri: 5,
+  sat: 6,
+};
+
+/**
+ * Derives a 5-field standard cron expression from a decomposed CronSpec value.
+ * Fields: minute hour day-of-month month day-of-week
+ */
+export const toCron = (value: CronSpecType): string => {
+  switch (value.frequency) {
+    case 'minutely':
+      return `*/${value.interval} * * * *`;
+
+    case 'hourly':
+      return `${value.minute} */${value.interval} * * *`;
+
+    case 'daily':
+      return `${value.minute} ${value.hour} * * *`;
+
+    case 'weekly': {
+      const dow = value.daysOfWeek.length > 0 ? value.daysOfWeek.map((d) => DOW_MAP[d]).join(',') : '*';
+      return `${value.minute} ${value.hour} * * ${dow}`;
+    }
+
+    case 'monthly': {
+      const dom = value.daysOfMonth.length > 0 ? value.daysOfMonth.join(',') : '*';
+      return `${value.minute} ${value.hour} ${dom} * *`;
+    }
+
+    case 'custom':
+      return value.cronExpression || '* * * * *';
+  }
+};
+
+const DOW_REVERSE: Partial<Record<string, DayOfWeek>> = {
+  '0': 'sun',
+  '1': 'mon',
+  '2': 'tue',
+  '3': 'wed',
+  '4': 'thu',
+  '5': 'fri',
+  '6': 'sat',
+  // Both 0 and 7 represent Sunday in standard cron.
+  '7': 'sun',
+};
+
+/** Returns a non-negative integer if the token is a valid decimal integer, otherwise undefined. */
+const parseUInt = (token: string): number | undefined => (/^\d+$/.test(token) ? Number(token) : undefined);
+
+/** Returns the parsed integer if it falls within [min, max], otherwise undefined. */
+const parseBoundedUInt = (token: string, min: number, max: number): number | undefined => {
+  const value = parseUInt(token);
+  return value !== undefined && value >= min && value <= max ? value : undefined;
+};
+
+/**
+ * Parses a 5-field cron expression into a CronSpec value.
+ * Recognises common patterns (minutely, hourly, daily, weekly, monthly) and falls back to `custom`.
+ */
+export const fromCron = (cron: string): CronSpecType => {
+  const parts = cron.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    return { frequency: 'custom', cronExpression: cron };
+  }
+
+  const [minute, hour, dom, month, dow] = parts;
+
+  // minutely: */N * * * *
+  const minutelyMatch = minute.match(/^\*\/(\d+)$/);
+  if (minutelyMatch && hour === '*' && dom === '*' && month === '*' && dow === '*') {
+    return { frequency: 'minutely', interval: parseInt(minutelyMatch[1]) };
+  }
+
+  // hourly: M */N * * *
+  const hourlyMatch = hour.match(/^\*\/(\d+)$/);
+  const minuteNum = parseBoundedUInt(minute, 0, 59);
+  if (hourlyMatch && dom === '*' && month === '*' && dow === '*' && minuteNum !== undefined) {
+    return { frequency: 'hourly', interval: parseInt(hourlyMatch[1]), minute: minuteNum };
+  }
+
+  const hourNum = parseBoundedUInt(hour, 0, 23);
+  if (minuteNum === undefined || hourNum === undefined) {
+    return { frequency: 'custom', cronExpression: cron };
+  }
+
+  // weekly: M H * * DOW[,DOW...]  (numeric DOW values only; all tokens must be valid)
+  if (dom === '*' && month === '*' && dow !== '*') {
+    const tokens = dow.split(',');
+    const days = tokens.map((d) => DOW_REVERSE[d]).filter((d): d is DayOfWeek => d != null);
+    if (days.length === tokens.length && days.length > 0) {
+      return { frequency: 'weekly', daysOfWeek: days, hour: hourNum, minute: minuteNum };
+    }
+    return { frequency: 'custom', cronExpression: cron };
+  }
+
+  // monthly: M H DOM[,DOM...] * *  (all tokens must be valid integers in 1-31)
+  if (dom !== '*' && month === '*' && dow === '*') {
+    const tokens = dom.split(',');
+    const days = tokens.map((d) => parseBoundedUInt(d, 1, 31)).filter((d): d is number => d !== undefined);
+    if (days.length === tokens.length && days.length > 0) {
+      return { frequency: 'monthly', daysOfMonth: days, hour: hourNum, minute: minuteNum };
+    }
+    return { frequency: 'custom', cronExpression: cron };
+  }
+
+  // daily: M H * * *
+  if (dom === '*' && month === '*' && dow === '*') {
+    return { frequency: 'daily', hour: hourNum, minute: minuteNum };
+  }
+
+  return { frequency: 'custom', cronExpression: cron };
+};
+
+/**
+ * Returns a human-readable description of a cron expression, e.g. "At 09:00 on Monday".
+ * Falls back to the raw expression string on parse errors.
+ */
+export const describeCron = (cron: string): string => {
+  try {
+    return cronstrue.toString(cron, { throwExceptionOnParseError: true });
+  } catch {
+    return cron;
+  }
+};

package/src/components/CronBuilder/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './CronBuilder';
+export * from './cron';
+export * from './schema';

package/src/components/CronBuilder/schema.ts

@@ -0,0 +1,119 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+export const MinutelySpec = Schema.Struct({
+  frequency: Schema.Literal('minutely').annotations({ title: 'Frequency' }),
+  interval: Schema.Number.pipe(Schema.between(1, 59)).annotations({
+    title: 'Every (minutes)',
+    description: '1–59',
+  }),
+});
+
+export const HourlySpec = Schema.Struct({
+  frequency: Schema.Literal('hourly').annotations({ title: 'Frequency' }),
+  interval: Schema.Number.pipe(Schema.between(1, 23)).annotations({
+    title: 'Every (hours)',
+    description: '1–23',
+  }),
+  minute: Schema.Number.pipe(Schema.between(0, 59)).annotations({
+    title: 'At minute',
+    description: '0–59',
+  }),
+});
+
+export const DailySpec = Schema.Struct({
+  frequency: Schema.Literal('daily').annotations({ title: 'Frequency' }),
+  hour: Schema.Number.pipe(Schema.between(0, 23)).annotations({
+    title: 'Hour',
+    description: '0–23',
+  }),
+  minute: Schema.Number.pipe(Schema.between(0, 59)).annotations({
+    title: 'Minute',
+    description: '0–59',
+  }),
+});
+
+// Named day-of-week literals for UX clarity; cron.ts maps them to numeric DOW values.
+export const DayOfWeek = Schema.Literal('sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat');
+export type DayOfWeek = Schema.Schema.Type<typeof DayOfWeek>;
+
+export const WeeklySpec = Schema.Struct({
+  frequency: Schema.Literal('weekly').annotations({ title: 'Frequency' }),
+  daysOfWeek: Schema.Array(DayOfWeek.annotations({ title: 'Day' })).annotations({ title: 'Days of week' }),
+  hour: Schema.Number.pipe(Schema.between(0, 23)).annotations({
+    title: 'Hour',
+    description: '0–23',
+  }),
+  minute: Schema.Number.pipe(Schema.between(0, 59)).annotations({
+    title: 'Minute',
+    description: '0–59',
+  }),
+});
+
+export const MonthlySpec = Schema.Struct({
+  frequency: Schema.Literal('monthly').annotations({ title: 'Frequency' }),
+  daysOfMonth: Schema.Array(Schema.Number.pipe(Schema.between(1, 31)).annotations({ title: 'Day' })).annotations({
+    title: 'Days of month',
+  }),
+  hour: Schema.Number.pipe(Schema.between(0, 23)).annotations({
+    title: 'Hour',
+    description: '0–23',
+  }),
+  minute: Schema.Number.pipe(Schema.between(0, 59)).annotations({
+    title: 'Minute',
+    description: '0–59',
+  }),
+});
+
+export const CustomSpec = Schema.Struct({
+  frequency: Schema.Literal('custom').annotations({ title: 'Frequency' }),
+  cronExpression: Schema.String.annotations({
+    title: 'Cron expression',
+    description: 'e.g. 0 9 * * MON-FRI',
+  }),
+});
+
+export const CronSpec = Schema.Union(
+  MinutelySpec,
+  HourlySpec,
+  DailySpec,
+  WeeklySpec,
+  MonthlySpec,
+  CustomSpec,
+).annotations({ title: '' });
+
+export type CronSpecType = Schema.Schema.Type<typeof CronSpec>;
+export type Frequency = CronSpecType['frequency'];
+
+export const Frequencies = [
+  'minutely',
+  'hourly',
+  'daily',
+  'weekly',
+  'monthly',
+  'custom',
+] as const satisfies readonly Frequency[];
+
+export const FrequencyLabels: Record<Frequency, string> = {
+  minutely: 'Every N minutes',
+  hourly: 'Hourly',
+  daily: 'Daily',
+  weekly: 'Weekly',
+  monthly: 'Monthly',
+  custom: 'Custom (cron)',
+};
+
+export const FrequencyDefaults: { [K in Frequency]: Extract<CronSpecType, { frequency: K }> } = {
+  minutely: { frequency: 'minutely', interval: 15 },
+  hourly: { frequency: 'hourly', interval: 1, minute: 0 },
+  daily: { frequency: 'daily', hour: 9, minute: 0 },
+  weekly: { frequency: 'weekly', daysOfWeek: ['mon'], hour: 9, minute: 0 },
+  monthly: { frequency: 'monthly', daysOfMonth: [1], hour: 9, minute: 0 },
+  custom: { frequency: 'custom', cronExpression: '* * * * *' },
+};
+
+export const CronBuilderSchema = Schema.Struct({ spec: CronSpec });
+export type CronBuilderSchemaType = Schema.Schema.Type<typeof CronBuilderSchema>;

package/src/components/index.ts

@@ -3,3 +3,4 @@
 //
 
 export * from './CreateAutomationPanel';
+export * from './CronBuilder';

package/src/containers/AutomationArticle/AutomationArticle.stories.tsx

@@ -0,0 +1,73 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { Trigger } from '@dxos/compute';
+import { Filter, Obj, Ref } from '@dxos/echo';
+import { useQuery } from '@dxos/react-client/echo';
+import { useClientStory, withClientProvider } from '@dxos/react-client/testing';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+import { Automation } from '#types';
+
+import { AutomationArticle } from './AutomationArticle';
+
+const DefaultStory = () => {
+  const { space } = useClientStory();
+  const [automation] = useQuery(space?.db, Filter.type(Automation.Automation));
+  if (!automation) {
+    return <Loading />;
+  }
+  return <AutomationArticle role='article' subject={automation} attendableId='story' />;
+};
+
+const meta = {
+  title: 'plugins/plugin-automation/containers/AutomationArticle',
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'fullscreen' }),
+    withClientProvider({
+      createIdentity: true,
+      createSpace: true,
+      types: [Automation.Automation, Trigger.Trigger],
+      onCreateSpace: async ({ space }) => {
+        space.db.add(Automation.make({ name: 'Morning Report', triggers: [] }));
+      },
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** Empty automation — no trigger or action yet. Exercises the disabled enabled-switch message. */
+export const Empty: Story = {};
+
+/** Automation with a timer trigger pre-configured for a daily 9 AM schedule. */
+export const WithTimerTrigger: Story = {
+  decorators: [
+    withClientProvider({
+      createIdentity: true,
+      createSpace: true,
+      types: [Automation.Automation, Trigger.Trigger],
+      onCreateSpace: async ({ space }) => {
+        const trigger = space.db.add(Trigger.make({ enabled: false, spec: { kind: 'timer', cron: '0 9 * * *' } }));
+        const automation = space.db.add(Automation.make({ name: 'Daily Digest', triggers: [] }));
+        // Wire the trigger into the automation after both are in the db.
+        Obj.update(automation, (automation) => {
+          automation.triggers = [...automation.triggers, Ref.make(trigger)];
+        });
+      },
+    }),
+  ],
+};